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, for the Django features, django>=4.2.

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, no API key. CLI entrypoint: lenscheck.

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

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@v1
        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 Django backend keeps a list of what it does — and can't lie about it. It records routes, models, and effects at runtime, diffs that contract in CI, and blocks undeclared effects while the app runs. 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. An undeclared call in error mode never leaves the process.

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

# apps.py / conftest.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 Django's real router + model registry — routes built in loops and DRF routers included.

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

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@v1
        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