Lenscheck documentation

Two packages. Every command, flag, and CI recipe in one place.

Install

The reviewer needs Python 3.8+, plus git and tar. The contract needs Python 3.10+ and your framework as an optional extra — pip install "lenscheck-contract[django]", [flask], [fastapi], or [celery].

Two vantage points

🔎 lenscheck-semantic-reviewer

A semantic PR reviewer for Python web apps. It reads the diff, tells you what it means and where to look, and can enforce a confirmed invariant corpus — no LLM. CLI entrypoint: lenscheck (needs a beta API key; your source never leaves — only facts are sent).

lenscheck review

Run a semantic review of a PR or commit range. With no repo, it reviews the current git repo's branch vs. its default branch.

lenscheck review <repo|url> --pr 128 --out pr_review.md --json pr_review.json --sarif pr_review.sarif

lenscheck post

Post a review to a PR — a sticky summary comment, optional inline comments, and one triage label.

lenscheck post 128 pr_review.md --json pr_review.json --inline --label

lenscheck serve (on-prem / self-hosted build)

Start the Lenscheck web UI to explore a repo/PR in the browser.

cd your-repo && lenscheck serve --port 8765

lenscheck invariants

Discover candidate invariants from a repo's history (ranked by how persistently they held), for a human to confirm into a corpus. the reviewer's own discovery — see also lenscheck-contract invariants

lenscheck invariants <repo> --snapshots 40 --out invariants.discovered.json

lenscheck digest

Org-wide leadership roll-up from the labels Lenscheck applies to PRs.

lenscheck digest --org my-org --repos repos.txt --slack $SLACK_WEBHOOK

GitHub Action

The zero-setup path. Add it to a pull_request workflow.

name: lenscheck
on: pull_request
permissions: { contents: read, pull-requests: write, issues: write }
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: AnkushSinghGandhi/lenscheck-semantic-reviewer@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          fail_on: crit          # violation | crit | none
          inline: true
          label: true

Outputs: review_markdown (pr_review.md) and review_sarif (pr_review.sarif).

🛡️ lenscheck-contract

Your Python backend — Django, Flask, or FastAPI — keeps a list of what it does, and can't lie about it. It records routes, models (Django, SQLAlchemy, Pydantic), effects, and Celery jobs at runtime, diffs that contract in CI, and blocks undeclared effects while the app runs (sync and async). CLI entrypoint: lenscheck-contract.

Decorators

Optional — Level 1 works with zero code. Declare what matters and the guard can enforce it.

from lenscheck_contract import contract

@contract.route("POST /orders", auth="user")     # method + path + who may call it
@contract.effects("net:api.stripe.com", "email") # every outside call it's allowed to make
def create_order(request):
    ...

@contract.job("nightly-invoices", schedule="0 2 * * *")
@contract.effects("net:api.stripe.com")
def nightly(): ...

Guard & middleware

The guard hooks the socket layer once — so requests, httpx, urllib, boto3, smtplib and anything else are all covered, sync and async (it hooks the asyncio event loop too, so httpx.AsyncClient / aiohttp are caught in-context). An undeclared call in error mode never leaves the process.

Install the request hook for your framework so every view is watched (not just decorated ones), then turn the guard on:

# Django — settings.py
MIDDLEWARE = ["lenscheck_contract.middleware.ContractMiddleware", ...]

# Flask
from lenscheck_contract import install_flask
install_flask(app)

# FastAPI
from lenscheck_contract import install_fastapi
install_fastapi(app)

# then, anywhere at startup (apps.py / conftest.py / main.py)
from lenscheck_contract import guard
guard.install(mode="error", allow=["net:*.internal"])   # off | record | warn | error

Don't know what to declare? Run tests in record mode, dump guard.suggestions(), and feed it to lenscheck-contract suggest.

lenscheck-contract export

Write the contract as JSON. Reads your framework's real router + models — routes built in loops, DRF routers, Flask blueprints, and FastAPI dependency trees included.

lenscheck-contract export --settings myproj.settings -o contract.json   # Django
lenscheck-contract export --no-django --app myapp.main:app -o contract.json   # Flask / FastAPI

lenscheck-contract diff

Compare two contract files (base vs head) and print what a reviewer cares about. This is the CI gate.

lenscheck-contract diff base.json head.json --markdown --fail-on risky

lenscheck-contract invariants

Emit a confirmed-invariant corpus for the reviewer's --invariants. This is the bridge — see below.

lenscheck-contract invariants --settings myproj.settings -o invariants.json

lenscheck-contract suggest

Turn a recorded run into ready-to-paste decorators.

lenscheck-contract suggest observed.json     # prints @contract.effects(...) per handler

🔗 The bridge: runtime truth → the reviewer

On its own the reviewer guesses your invariants from git history. lenscheck-contract hands it the truth: your app's declared egress destinations become an enforced allowlist, and its auth/PII rules are confirmed. A brand-new domain sneaking into a PR then becomes a 🔴 critical alert — grounded in fact.

# 1. export the real contract as an invariant corpus (runs your app)
lenscheck-contract invariants --settings myproj.settings -o invariants.json

# 2. hand it to the reviewer — it stops guessing, it enforces
lenscheck review <repo> --pr 128 --invariants invariants.json --fail-on violation

Full CI — both tools on one PR

name: pr-checks
on: pull_request
permissions: { contents: read, pull-requests: write, issues: write }

jobs:
  # 1) the reviewer — comments on the PR (soft heads-up)
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: AnkushSinghGandhi/lenscheck-semantic-reviewer@v2
        with: { github_token: "${{ secrets.GITHUB_TOKEN }}", fail_on: crit }

  # 2) the contract — hard gate on structural change (+ feeds the reviewer)
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: pip install -e . lenscheck-contract
      - run: lenscheck-contract export --settings app.settings -o head.json
      - run: lenscheck-contract invariants --settings app.settings -o invariants.json
      - run: git checkout ${{ github.base_ref }}
      - run: lenscheck-contract export --settings app.settings -o base.json
      - run: lenscheck-contract diff base.json head.json --markdown --fail-on risky

The third catch — the runtime guard — runs in your test/staging job, because it needs the app actually running (guard.install(mode="error")).

← Back to home  ·  Reviewer on GitHub  ·  Contract on GitHub