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

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.