gaze-py

gaze-py is a Python-native port of gaze, the GazeCRAP analysis engine. It detects observable side effects in Python functions using AST-only static analysis (no code execution, no imports of analysed modules), classifies each effect as contractual or incidental using a five-signal confidence engine, and computes CRAP and GazeCRAP scores to surface functions that are both complex and under-tested. The output is schema-compatible with the Go gaze implementation.

Documentation — concepts, getting-started guide, CLI reference, configuration, glossary.

Requirements

• Python 3.11+

Installation

# Run without installing (recommended for one-off use)
uvx --from gaze-py gazepy --help

# Permanent install
uv tool install gaze-py

# Or with pip
pip install gaze-py

Basic usage

# Analyse a source directory (CRAP will be null — no coverage provided)
gazepy analyze src/

# JSON output (default)
gazepy analyze src/ --format=json

# Human-readable text output (one line per function)
gazepy analyze src/ --format=text

# CRAP scoring — auto-runs pytest for coverage
gazepy crap src/

# CRAP scoring with a pre-generated coverage report
gazepy crap src/ --coverprofile cov.json

# Assess test quality and compute GazeCRAP scores
gazepy quality src/

# Scaffold OpenCode agent and command files into .opencode/
gazepy init

CRAP scoring with gazepy crap

CRAP scoring requires line coverage data. The crap command can collect coverage automatically by running pytest, or accept a pre-generated coverage.py JSON report:

# Auto-run pytest and collect coverage (requires pytest-cov)
gazepy crap src/

# Use a pre-generated coverage report (recommended in CI to avoid a double test run)
pytest --cov=your_package --cov-report=json:cov.json
gazepy crap src/ --coverprofile cov.json

# Fail CI if crapload exceeds a threshold
gazepy crap src/ --max-crapload 30

When coverage is provided, the line_coverage and crap fields are populated in the output. When omitted, those fields are null (not 0.0) — null means "not measured", not "zero coverage".

The analyze command detects side effects only — it does not compute CRAP scores. Use gazepy crap for CRAP scoring.

Quality assessment with gazepy quality

gazepy quality runs the full O1 pipeline: pairs test functions to their production targets, detects assertion sites, maps assertions to detected side effects, and computes GazeCRAP using contract coverage (the fraction of contractual effects covered by tests).

# Assess test quality — auto-discovers tests/ directory
gazepy quality src/

# Explicit tests directory
gazepy quality src/ --tests tests/

# JSON output
gazepy quality src/ --format=json

# Fail CI if average contract coverage drops below a threshold
gazepy quality src/ --min-contract-coverage 80

Assert captured output

Assert the returned value and emitted content separately so quality reports can distinguish the two contracts. For example, put this function in example.py:

def run_example():
    print("ready")
    return 0

In test_example.py, import the function explicitly so the mapper can identify the source of the captured output:

from example import run_example


def test_run_example(capsys):
    result = run_example()
    assert result == 0
    stdout, _ = capsys.readouterr()
    assert stdout == "ready\n"

The mapper recognizes capsys and capfd fixture parameters, tuple unpacking, saved capture results such as captured.out, directly assigned stdout = capsys.readouterr().out, and inline captured-stream assertions. Assertions on .out cover stdout; assertions on .err cover stderr.

For JSON output, use an unshadowed import json and payload = json.loads(captured.out), with exactly one positional argument and no keywords. Read-only indexing and equality or membership assertions retain the stream provenance. Aliases of json, imported loads functions, decoding hooks, arbitrary methods and helper transformations are outside this supported subset. Mutating a parsed value or any nested descendant, or passing it to an unknown helper, invalidates provenance for the entire parsed value and its aliases.

Calls need a resolvable, unshadowed import that identifies the exact target module and function. Direct function imports and supported module imports can establish that identity; a matching bare name or method name is not enough. Package identity uses the import root, not a source-path suffix. Unresolved imports and namespace packages without an authoritative import root remain uncovered.

Capture reads drain the buffer. A later read without another target call does not verify the earlier output; a saved captured value remains usable until it is overwritten. Keep the target call and capture in a clear sequence. The mapper leaves uncertain provenance uncovered, including unsupported control flow, unrelated producers, arbitrary helper transformations and nested definitions. A conditional capture read can consume output and invalidate pending attribution; it cannot establish a clean buffer. Only a definite read followed by a supported target call can restore that isolation. It analyzes syntax and never executes analyzed code.

Return bindings are checked at the assertion's position. Reassigning a return variable to a capture does not preserve return credit. A live return keeps precedence when mixed with a supported captured stream, but an assertion that mixes a return with unsupported capture provenance remains unmapped. Keep those assertions separate to make both contracts visible.

When a test uses a context manager, isolate its lifecycle from the output being tested: drain the fixture after entering the context, call the target, and save the captured output before leaving the context. Assertions can inspect that saved snapshot afterward. A fresh capture after context exit may include unrelated output and is left uncovered. Concurrent/background writers cannot be attributed by this bounded static analysis.

See Understanding the output for the measured fields and the changelog for mapping corrections.

Understanding the output

Each function in the output includes:

The summary section includes recommended_actions — up to 20 functions sorted by priority (add_tests → decompose_and_test → decompose) that exceed the CRAP threshold.

AI Reports

gazepy report can pass the analysis JSON to a local or cloud AI provider to generate a narrative interpretation. Configure your provider in .gaze.yaml:

ai:
  provider: ollama       # or: vertex
  model: llama3.2:3b     # any Ollama model, or a Vertex Claude model ID
  endpoint: http://localhost:11434   # Ollama only; ignored for Vertex
  timeout: 120           # seconds per HTTP request (default: 120)

For Google Vertex AI (Claude models):

ai:
  provider: vertex
  model: claude-sonnet-4-6
  project: my-gcp-project
  region: us-east5

Environment variable overrides (higher precedence than config file):

Prerequisites:

• Ollama: install from ollama.com and pull your model (ollama pull llama3.2:3b)
• Vertex: install the Google Cloud SDK and run gcloud auth application-default login

If no provider is configured, gazepy report emits the raw analysis JSON to stdout and a tip to stderr.

Migration from --ai flag: the --ai and --ai-timeout flags have been removed. Configure your provider in .gaze.yaml instead (see above).

Troubleshooting

Releasing

Releasing a new version

1. Bump version in pyproject.toml and __version__ in src/gaze_py/__init__.py in a PR. Merge to main.
2. Go to GitHub Actions → Release → Run workflow.
3. Enter the tag matching the version (e.g. v0.3.0).
4. Approve the pypi environment gate if configured.
5. The workflow validates, tags, builds, and publishes automatically.