*Git shows you what lines changed. Lenscheck shows you what they mean, where to look, and whether
they broke a rule. It's a semantic PR reviewer for Python web apps. This guide starts from zero β
every idea, command, and setting in plain English β then shows you how to set Lenscheck up once and
run it across all your repos (personal, team, or organization).*
No LLM Β· Deterministic Β· Never runs your code Β· Nothing leaves your network
Try it on a repo you already have β see the review right in your terminal:
pip install lenscheck-semantic-reviewer
cd your-django-repo
lenscheck review # your current branch vs. main β the few things that actually matter
Turn it on for a team β one command (drops a GitHub Action that reviews every PR, advisory only):
lenscheck init # writes .github/workflows/lenscheck.yml (comments, never blocks)
git add .github/workflows/lenscheck.yml && git commit -m "add lenscheck" && git push
Prefer to click around? lenscheck serve opens a local web UI with the flow graph.
That's the whole tool: a flow graph of what a PR does, and rules it can enforce. Everything
below is depth for when you want it.
When you open a Pull Request (PR), the reviewer sees a diff β red lines removed, green lines
added. But a diff tells you what text changed, not what it means. Did this PR add a new way
into your app? Did it start writing to your database without a login check? Did someone's email
address just start leaving your server?
Lenscheck reads your PR and tells you what it means β in a few high-signal findings, each pointing
at the exact line to look at. It's built for Python web apps (Django / Django REST Framework today).
It is not an AI that guesses. It reads your code with Python's own parser and reports facts.
When it isn't sure, it says so (you'll see a β ). It never dresses up "I didn't see it" as "it's safe."
Lenscheck has a lot of features, but they exist to serve two that matter most. If you remember
nothing else from this guide, remember these two.
The problem. A git diff shows you text β hundreds of red and green lines. It doesn't tell you
that one of them opened a new endpoint, started writing to the database, or sent a user's email out
of the building. On a big (often AI-generated) PR, the reviewer skims β and the risky change ships.
What Lenscheck does. It reads the code before and after the PR and turns the diff into
meaning: what changed β how it flows β where to look. A huge diff becomes a short, ranked list
plus a flow graph of each change (route β auth β DB tables β external β cache β async β PII). On a
real 17,841-line PR, that came out to 3 things to look at.
Git tells you what lines changed. Lenscheck tells you what those changes mean.
The problem. Every codebase has rules everyone "knows" β auth before any DB write, personal data never leaves without a login β but nothing actually enforces them. A PR quietly breaks one, and
What Lenscheck does. It discovers those rules from your git history, lets you confirm the
real ones, then enforces them on every PR β flagging (and optionally blocking) a new violation
while ignoring existing debt. This is the part that compounds: over time Lenscheck learns the rules
your codebase cares about, and no competitor has that knowledge.
Everything else is in service of these two. Intent-vs-behaviour contradictions, traced PII leaks,
dependency-capability scanning, SARIF, inline comments, labels, the org roll-up β all of it makes the
two features above sharper. The rest of this guide explains each one, but if the list ever feels like
a lot: it's a flow graph and enforced rules. That's the product.
pip install lenscheck-semantic-reviewer
That's it β Lenscheck has zero dependencies (it only uses Python's standard library). You now have a
lenscheck command. Check it:
lenscheck --help
Lenscheck Semantic Reviewer
Usage: lenscheck <command> [options]
Commands:
init Add the GitHub Action to this repo (one-command setup)
review Run a semantic review of a PR or commit range
post Post a review to a PR (sticky comment, inline comments, label)
serve Start the Lenscheck web UI
invariants Discover baseline invariants from a repository's history
digest Org-wide roll-up from the labels Lenscheck applies to PRs
You can use Lenscheck in whichever way fits:
lenscheck serve, open your browser, click around. Best for lenscheck review β¦. Best for They all share the same engine, so they find the same things.
Start it inside any repo:
lenscheck serve
It prints a URL (like http://127.0.0.1:8765/) and opens your browser. If you run it inside a git
repo, it auto-detects that repo for you.
Along the top you pick what to compare. You have four ways:
main β my-feature).
Once a review runs, you read it top-to-bottom. Using the screenshot above:
The one-line summary β "This PR adds 1 endpoint, 1 new DB write to AuditLog, 1 new
external call⦠and 4 new PII signals." A plain-English sentence of everything that changed,
built from facts. (the intent summary)
π Intent vs. behavior β the red panel. The PR called itself a "refactor / no behavior change," but Lenscheck found it
π¦ Dependency capability changes β bumped libraries and whether the new version can do more
than the old one. (dependency scanning)
The tally β π΄ 1 β how many findings at each severity.
The change list (left) β one row per changed endpoint, worst first. Click a row to seeβ¦
The flow graph (right) β a live picture of what that endpoint does. In the screenshot,
ExportUsers β reads User (SQL table auth_user), writes AuditLog ( audit_log), calls
hooks.example.com, reads and writes the cache, and dispatches two async jobs
(reindex_users, a thread) β every edge colored by kind, with the new parts highlighted. This is
the same picture Lenscheck can also draw as a
Mermaid diagram inside a GitHub comment.
The "Where to look" tab β switch the detail pane from the graph to a flat, ranked list of
every fact with its exact file:line β the WHERE of the review, including the traced leak.
Click any block in the graph (or a line here) and Lenscheck shows you the source, with the exact
line highlighted:
Click β Invariants in the top bar:
Lenscheck samples your git history and shows candidate rules it noticed your codebase following. In
the screenshot:
[boundary] β holds ExportUsers change dangerous: the new endpoint would send an email to a
This is the moat β over time you teach Lenscheck the rules your codebase cares about, and no
competitor has that knowledge. (invariants)
Note: the Confirm buttons only appear if you started the server with a place to save them:
lenscheck serve --invariants my-rules.json. Without that, the panel is read-only (Lenscheck never writes
a file you didn't ask for).
http://β¦/?open=0 β deep-link that opens the review with the first change already selected.http://β¦/?invariants=1 β deep-link that opens the Invariants panel automatically.lenscheck init β one-command setup
Drops a ready-to-run GitHub Action into the current repo β the fastest way to adopt.
lenscheck init # writes .github/workflows/lenscheck.yml in advisory mode (comments, never blocks)
lenscheck init --gate # start it blocking on a confirmed-rule violation instead
lenscheck init --force # overwrite an existing workflow
It refuses to clobber an existing workflow unless you pass --force, and prints the two remaining
steps (commit, open a PR). Start advisory; switch to --gate once your rules are confirmed and trusted.
lenscheck review β the main event
Analyze a PR / branch / commit and print a review.
The same review as a self-contained HTML file (--html) you can send to anyone β no install
needed:
lenscheck review # no args: review THIS branch vs the default branch
lenscheck review /path/to/repo --base main --head my-feature
lenscheck review https://github.com/owner/repo --pr 123
Positional argument:
| Argument | Meaning |
|---|---|
repo |
A local folder or a GitHub URL.Optional β leave it out and Lenscheck uses the repo you're standing in. |
Flags β how to pick what to compare (choose one; or none to auto-detect):
| Flag | What it does |
|---|---|
| (nothing) | Review the current branch vs. the default branch . The zero-effort mode. |
--pr 123 |
Review a real GitHub Pull Request by number (needs a GitHub URL as the repo). |
--base X --head Y |
Review the difference between two refs (branches, tags, or commit SHAs). |
--commit SHA |
Review a single commit (compares it against its parent). |
--merge SHA |
Review a merge commit (compares its two parents). |
Flags β what to produce:
| Flag | What it does |
|---|---|
--out FILE |
Where to write the Markdown report. Default: pr_review.md . |
--json FILE |
Also write the full review as structured JSON (for tools/automation). |
--html FILE |
Also write a self-contained HTML viewer you can open in a browser. |
--sarif FILE |
Also write SARIF β the format GitHub reads to show findings in its Security tab. (SARIF output) |
--invariants FILE |
Enforce a confirmed rules file: flag any endpoint in this PR that breaks a rule. |
--fail-on violation |
Exit with an error if the PR breaks a confirmed rule. (Use in CI to block merges.) |
--fail-on crit |
Exit with an error on any π΄ finding. |
lenscheck post β put the review on the PR
Takes a review you already generated and posts it to a GitHub PR.
lenscheck post 123 pr_review.md --json pr_review.json --inline --label
| Argument / flag | What it does |
|---|---|
123 |
The PR number. |
pr_review.md |
The Markdown body to post as a sticky comment (it updates in place on re-runs). |
--json FILE |
The structured review (needed for --inline and--label ). |
--inline |
Post each finding as a comment pinned to the exact changed line . (inline comments) |
--label |
Put one lenscheck:*label on the PR based on its worst finding. (auto-label) |
--dry-run |
Print what would be posted, without touching GitHub. Great for testing. |
(Needs a GITHUB_TOKEN env var and the gh CLI, which GitHub's runners already have.)
lenscheck serve --repo /path/to/repo --port 8765
| Flag | What it does |
|---|---|
--repo |
Repo to preload (default: the git repo of the current folder). |
--invariants FILE |
The rules file to enforce and the file the Confirm buttons write to. |
--port /--host |
Where to serve (default 8765 on0.0.0.0 ). |
--pr /--commit /--merge /--base /--head |
Open straight into a specific review on load. |
--no-open |
Don't auto-open a browser window. |
Useful environment variables for a hosted deployment:
| Env var | What it does |
|---|---|
PORT /HOST |
Where to bind (hosts like Render set PORT ; defaultHOST is0.0.0.0 ). |
LENSCHECK_TOKEN |
Require ?token=β¦ on API calls βset this on any public deployment. |
LENSCHECK_ALLOWED_REPOS |
Comma-separated allow-list; only matching repos may be reviewed. |
LENSCHECK_BASE_PATH |
Serve under a sub-path (e.g. /lenscheck ) behind a reverse proxy. |
LENSCHECK_DEFAULT_REPO |
The repo shown by default in the UI. |
LENSCHECK_INVARIANTS |
Default invariant corpus path to enforce in the UI. |
LENSCHECK_CACHE |
Where cloned repos are cached (default ~/.cache/lenscheck/repos ). |
LENSCHECK_GIT_TIMEOUT |
Seconds before a git clone /archive is aborted (guards huge repos). |
GITHUB_TOKEN |
For private repos / to avoid GitHub rate limits. |
To host one shared Lenscheck UI: run lenscheck serve --no-open behind your usual reverse proxy, set
LENSCHECK_TOKEN (so the API isn't open), and optionally LENSCHECK_ALLOWED_REPOS to fence it to just your
repos. To run Lenscheck across all your repos from one place, see
Β§9 β Set up Lenscheck for all your repos.
lenscheck invariants β discover, confirm, and blame rules
Three jobs in one command.
Discover β look through git history and propose candidate rules:
lenscheck invariants /path/to/repo --snapshots 8
| Flag | What it does |
|---|---|
--snapshots N |
How many points in history to sample (more = slower but more confident). |
--out FILE |
Where to write the discovered candidates (JSON). |
--report FILE |
Where to write a human-readable report (Markdown). |
Confirm β turn candidates into a rules file without hand-editing JSON:
lenscheck invariants --confirm # interactive: press c / f / s / q per rule
lenscheck invariants --confirm --id auth-before-write --owner security # scripted
| Flag | What it does |
|---|---|
--confirm |
Enter confirm mode. Interactive unless you pass --id or--all . |
--in FILE |
The discovered candidates to read from. |
--corpus FILE |
The confirmed rules file to create/update. |
--id NAME |
Confirm a specific rule (repeatable). |
--all |
Confirm every candidate. |
--owner NAME |
Record who owns the rule. |
--drop-baseline |
Treat today's exceptions as bugs to fix , not as accepted. |
In interactive mode you press one key per rule: c onfirm Β· f ix (confirm, but the current
exceptions are bugs) Β· s kip Β· q uit.
Blame β find the commit that first broke a rule (semantic blame):
lenscheck invariants /path/to/repo --blame auth-before-write --exact
| Flag | What it does |
|---|---|
--blame NAME |
Which rule to investigate. |
--route R |
Only blame a specific endpoint. |
--exact |
Pinpoint the precise commit (binary-searches history; a bit slower). Without it, you get the window between two sampled snapshots. |
lenscheck digest β the org-wide roll-up for leadership
Every other command answers "is this PR risky?". digest answers the question a manager
actually asks: "across all our repos, how much risk is sitting in review right now?" β in one
short message, with no re-analysis and no GitHub Advanced Security.
It works by counting labels. Each PR review applies exactly one lenscheck:* triage label
(auto-label); the digest just searches an org for the open PRs still
carrying each one:
lenscheck digest --org my-org --slack "$SLACK_WEBHOOK"
*Lenscheck digest β my-org* (open PRs by risk)
π΄ 4 security / PII / unauth write
π 9 money path
π‘ 12 new DB write / external
With --slack, that lands in your channel every morning β one number the whole team (and leadership)
can read without opening a single PR:
| Flag | What it does |
|---|---|
--org ORG |
The GitHub org/owner to summarize ( required ). |
--repos FILE |
Optional file of owner/repo lines β adds an adoption line: how many repos have the workflow live and a confirmed invariants file. |
--slack URL |
Post the digest to a Slack incoming webhook (otherwise it just prints). |
Needs a GITHUB_TOKEN with org read access (the default per-repo token can't search the org).
An honesty rule carries over from the analyzer: a tier it couldn't fetch shows ?, never a
fake 0. Run it on a schedule (a weekly cron in a central repo) and it becomes the standing
answer to "is Lenscheck worth keeping on?" β because the labels feed it, keep label: true and
issues: write on your review workflow.
Each heading below is the problem the feature solves. The first two are the headline features from
Β§2; everything after them is supporting cast that sharpens those two.
Skim to what's relevant β you don't need to read all eleven.
The semantic diff, severity & flow graph β headline feature β . Lenscheck analyzes your code
before and after the PR and reports the change in behavior. Renaming a function with no
behavior change? Silence (that's a good thing). Adding an unauthenticated database write? π΄. Every
finding is ranked π΄/π /π‘/π’, points at a file:line, and gets a flow graph of what the endpoint
does (route β auth β DB tables β external β cache β async β PII).
Invariants: discover, confirm, enforce, blame β headline feature β‘. The compounding asset. Four steps:
β NEAR-MISS β Authenticated access before any DB write
- holds: 3/4 endpoints (75%) Β· persistence: 100% β 100% β 100% β 75% across 4 snapshots
- exceptions β look here (1):
- api/users/export β open (AllowAny) (shop/views.py:40)
Confirm (lenscheck invariants --confirm, or the web button) β mark the ones that are real. Saved
to a rules file. No JSON editing.
Enforce (lenscheck review --invariants rules.json) β every future PR that breaks a confirmed
rule gets a π΄, and --fail-on violation can block the merge.
Blame (lenscheck invariants --blame β¦ --exact) β find exactly which commit broke a rule:
π©Έ auth-before-write first broke at e23c96a (exact, in window 3e9817b..e23c96a)
holds 3/4 at the snapshot.
offending endpoint(s):
- api/users/export β open (AllowAny) (shop/views.py:40)
Bootstrap (turn it on everywhere, no human): confirming rules per repo doesn't scale to 20
repos. lenscheck invariants <repo> --bootstrap --baseline org-baseline.json discovers the rules,
auto-confirms the safe ones, and freezes today's state as the baseline β so the rule file is a
ratchet: it only fires on a new violation a PR introduces, never on existing debt. Seed it
with a shared org baseline (the universal rules) and every repo inherits the same policy; each
repo's own exceptions are filled in automatically. Auto-confirmed rules are tagged
owner: auto-bootstrap so a human can review them later. This is what makes the moat adoptable
across a whole org instead of one repo at a time.
Everything below supports the two above.
The intent summary. One plain-English sentence at the top of every review, built from verified facts:
"This PR adds 1 endpoint, 1 new DB write to AuditLog, 1 new external call to
hooks.example.com/export and 4 new PII signals."
Other tools generate this with an AI that reads the diff and sometimes makes things up. Lenscheck counts
real facts, so every number traces to a line.
Intent vs. behavior. Your PR title/description is a promise. Lenscheck checks it against the facts.
From the demo, the PR titled "refactor: tidy up user views" got caught twice:
π Intent vs. behavior β PR describes itself as "refactor / no behavior change", but the facts disagree
π΄ claims refactor / no behavior change, but adds an endpoint β api/users/export @ shop/views.py:40
π΄ claims refactor / no behavior change, but new PII signal: email β log.info β api/profile @ shop/views.py:32
PII taint β the precision feature. Old tools say "personal data and an external call are both in this function β maybe it leaks." Vague. Lenscheck
email β requests.post @ line 46. The exact field, the exact exit, the exact line.
It also resolves fuzzy database writes: for order in Order.objects.filter(...): order.save() is now
understood as writing the Order table, not a vague <instance>.
Dependency capability-delta. When a PR bumps a library, Lenscheck downloads the old and new
versions and compares what each can do β checking for network / subprocess / native code / file writes / reading secrets. It reports only the
requests 2.28β2.31: no new capabilities π’leftpad 1.0β2.0: now spawns a subprocess π΄
If it can't fetch a version (offline, or the package has no source), it says β unresolved β never
"safe":
π¦ Dependency capability changes
β requests 2.28.0β2.31.0 β capabilities not statically resolved (offline or no sdist)
β six 1.15.0β1.16.0 β capabilities not statically resolved (offline or no sdist)
Turn the network scan off with LENSCHECK_SCAN_DEPS=0 (or the Action's scan_deps: false) and you'll
always get the fast β mode.
Mermaid flow diagram. Every review's Markdown includes a Mermaid sequence diagram of the
beforeβafter flow. GitHub renders it right inside the PR comment β a real picture of your endpoint's
behavior, drawn from facts, not by an AI:
mermaid sequenceDiagram participant Client participant NExportUsers as ExportUsers Client->>NExportUsers: π POST api/users/export NExportUsers->>Database: write AuditLog NExportUsers->>Database: read User NExportUsers->>External: https://hooks.example.com/export GitHub renders that right inside the PR comment β a real picture of the endpoint's behavior, drawn
from facts:
Inline PR comments. lenscheck post β¦ --inline pins each finding as a comment on the exact line. The honest guard: it only pins a comment where it can prove the line is in the diff (GitHub
Auto-label. lenscheck post β¦ --label puts one triage label on the PR based on its worst
finding: lenscheck:π΄security / lenscheck:π payment / lenscheck:π‘new-write /
lenscheck:π’safe-refactor. Makes a queue of PRs scannable at a glance.
SARIF output. --sarif pr_review.sarif writes a standard file GitHub understands. Upload it and
your findings show up on the exact changed lines in the PR's "Files changed" tab and in the repo's
Security tab β native, official, high-visibility.
Smart default target. Running lenscheck review with no arguments inside a repo just does the
obvious thing: reviews your current branch vs. the default branch. If you're on the default
branch, it tells you to switch to a feature branch instead of guessing.
Add this workflow and Lenscheck reviews every PR automatically:
name: Lenscheck Semantic Review
on: pull_request
permissions:
contents: read
pull-requests: write # to post comments
issues: write # to apply the label
security-events: write # to upload SARIF
jobs:
lenscheck:
runs-on: ubuntu-latest
steps:
- uses: AnkushSinghGandhi/lenscheck-semantic-reviewer@v1
with:
fail_on: none # or: violation | crit
Every input:
| Input | Default | What it does |
|---|---|---|
github_token |
auto | Token for reading the PR and posting back. |
fail_on |
none |
violation fails the build on a broken rule;crit fails on any π΄. |
invariants |
(none) | Path to a confirmed rules file to enforce. |
comment |
true |
Post the sticky summary comment. |
inline |
true |
Also post inline comments on changed lines. (inline) |
label |
true |
Apply one lenscheck:* label. (label) |
scan_deps |
true |
Scan bumped dependencies against PyPI. Set false to skip the network (findings become β ). (deps) |
upload_sarif |
true |
Upload SARIF to code scanning. Set false on private reposwithout GitHub Advanced Security so the step is skipped and the check stays green. |
The Action uploads SARIF (when upload_sarif is on), so findings appear in the Security tab β
that surface needs GitHub Advanced Security on private repos. Without GHAS, the same findings still
arrive as the PR comment, inline comments, and label, and an org-wide roll-up is available via
lenscheck digest (below).
Section 8 put Lenscheck on one repo. This section turns it on across every repo you own β
personal projects, a team's services, or a whole company β from one place, with almost no
per-repo work.
The trick: host the workflow once, and have every repo point at it. Then you switch Lenscheck on (or
change how it behaves) by editing a single file, not twenty. It's the same steps whether you have 1
repo or 100.
Make a repo β call it lenscheck-workflows (under your username or org) β and add the real workflow
there once, as a reusable workflow:
name: Lenscheck
on: { workflow_call: {} }
permissions: { contents: read, pull-requests: write, issues: write }
jobs:
lenscheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: AnkushSinghGandhi/lenscheck-semantic-reviewer@v1
with:
comment: 'true'
fail_on: none # observe mode β never blocks a merge (yet)
upload_sarif: false # set true only if you have GitHub Advanced Security
Then every repo gets a tiny 3-line caller that just points at it:
name: Lenscheck
on: { pull_request: {} }
jobs:
lenscheck:
uses: your-name/lenscheck-workflows/.github/workflows/lenscheck.yml@v1
permissions: { contents: read, pull-requests: write, issues: write }
Now updating Lenscheck everywhere means editing one file in lenscheck-workflows. That's the
"centralised" part β and it's identical for a personal account, a team, or an org.
Notice fail_on: none above. That's observe mode: Lenscheck posts its review on every PR but
can never block a merge. Zero risk β you and your team see the value for a week or two before it
can ever get in the way. You turn on blocking later, once you trust it (Step 5).
Keep issues: write + label: 'true' on. Lenscheck puts one lenscheck:* label on each PR, and Step 4's
roll-up counts those labels β no label, no roll-up.
Adding the caller to many repos: for a handful, paste it in by hand. For a lot, a small script
that loops your repo list and opens the 3-line PR on each (using the gh CLI) does it in one go β or,
on GitHub Enterprise, an org "required workflow" applies it automatically.
This is the part that makes Lenscheck yours: enforcing the promises your code already keeps
("always log in before writing to the DB", "personal data never leaves without auth"). Normally you'd
discover rules, confirm each by hand, and commit a file β fine for one repo, tedious for many.
lenscheck invariants --bootstrap does it with no human:
lenscheck invariants <repo> --bootstrap --baseline org-baseline.json --out lenscheck-invariants.json
It finds the repo's rules, auto-confirms the safe ones, and freezes today's state as the starting
line β so it only ever complains about a new violation a future PR introduces, never your existing
code. Zero noise.
Write your shared rules once in an org-baseline.json (start from
org-baseline.sample.json) β the universal ones like auth before any DB write and
lenscheck-invariants.json, and the workflow enforces it from then on.
Per-PR comments help whoever's on that PR. For the big picture β how many risky PRs are open right now β
lenscheck:* label:
lenscheck digest --org your-github-org --slack "$SLACK_WEBHOOK"
π΄ 4 security / PII / unauth write
π 9 money path
π‘ 12 new DB write / external
No re-analysis, and no GitHub Advanced Security needed β it just reads the labels. Run it on a
weekly schedule and pipe it to Slack. (This one aggregates a whole GitHub org; for personal repos
the per-PR labels already give you the same signal on each PR.)
Once people trust the reviews, flip the switch in your one central file β and only for the
highest-confidence signal:
- uses: AnkushSinghGandhi/lenscheck-semantic-reviewer@v1
with:
fail_on: violation # block only when a PR breaks a confirmed rule
Never block on "any π΄" from day one β that's how a tool gets switched off. Block only on a new rule violation, once your rules are confirmed and trusted.
If other people will depend on this, mirror the Action into your own account/org and pin a commit SHA instead of pointing at a public
@v1 tag β the reusable workflow means you fix that in one
Here's the exact scenario from the screenshots. A developer opens a PR titled
"refactor: tidy up user views." It claims to be a harmless cleanup. In reality it:
POST /api/users/export with AllowAny), AuditLog table and GET /api/profile to requests and six.
Run it:
lenscheck review /path/to/repo --commit <sha> --sarif out.sarif
Lenscheck produces, in one pass:
api/users/export: email β requests.post @ shop/views.py:46.
Every single item points to a line you can click. Nothing was guessed.
Lenscheck's whole value is that you can trust it. So it follows strict rules:
file:line.
lenscheck review # this branch vs default branch
lenscheck review . --base main --head feature # two refs
lenscheck review URL --pr 123 # a GitHub PR
lenscheck review . --commit <sha> # one commit
lenscheck review . --sarif out.sarif --html r.html # extra outputs
lenscheck review . --invariants rules.json --fail-on violation # enforce + block
lenscheck post 123 pr_review.md --json pr_review.json --inline --label
lenscheck post 123 pr_review.md --dry-run # preview, no posting
lenscheck serve # this repo
lenscheck serve --repo . --invariants rules.json # + enable Confirm buttons
lenscheck invariants . # discover candidate rules
lenscheck invariants --confirm # confirm interactively
lenscheck invariants --confirm --id auth-before-write --owner security
lenscheck invariants . --bootstrap --baseline org-baseline.json # auto-confirm + ratchet (no human)
lenscheck invariants . --blame auth-before-write --exact # who broke it
lenscheck digest --org my-org # open PRs by lenscheck:* label
lenscheck digest --org my-org --repos repos.txt --slack "$SLACK_WEBHOOK" # + adoption, to Slack
LENSCHECK_SCAN_DEPS=0 # skip the dependency network scan
LENSCHECK_TOKEN=β¦ # lock down a hosted `lenscheck serve`
LENSCHECK_CACHE=β¦ # where cloned repos are cached (default ~/.cache/lenscheck/repos)
LENSCHECK_GIT_TIMEOUT=β¦ # seconds before a git clone/archive is aborted
You'll meet these terms everywhere. Here they are in plain English.
Endpoint β a single "door" into your web app. A URL + the code that runs when someone hits it.
Example: POST /api/users/export runs the ExportUsers function. Lenscheck reviews your PR one
endpoint at a time.
The 7-edge lens β for each endpoint, Lenscheck asks seven simple questions (these are the "edges"):
| Edge | The question it answers |
|---|---|
| Route | What URL is this, and which function handles it? |
| Auth | Do you need to be logged in? (or is it open to anyone?) |
| DB | Does it read or write the database? Which tables? |
| External | Does it call the outside world? (Stripe, a webhook, an APIβ¦) |
| Async | Does it kick off a background job? (Celery, a threadβ¦) |
| Cache | Does it read or invalidate the cache? Which keys? |
| PII | Does it touch personal data (email, phone, addressβ¦)? |
Severity colors β Lenscheck ranks every finding by how much it should worry you:
PII β "Personally Identifiable Information": personal data like an email, phone number, address, password, card number. Leaking it is a legal and trust problem.
PII egress β "egress" just means leaving. PII egress = personal data leaving your server β sent to an external API, written to a log, or returned to the browser. That's the moment
Taint β following a piece of data as it moves through the code. If an email is "tainted," Lenscheck
watches whether that exact value reaches an exit (an external call, a log, a response). If it
does, that's a confirmed leak.
Invariant β a rule your codebase has always followed, whether or not anyone wrote it down.
Example: "every endpoint that writes to the database first checks you're logged in." Lenscheck can
discover these from your git history, let you confirm the real ones, and then enforce
them on every PR.
Semantic diff β a normal diff compares text. A semantic diff compares meaning: Lenscheck
analyzes your code before and after the PR and reports the difference in behavior (new
endpoints, new DB writes, new callsβ¦), ignoring cosmetic changes like renaming a function.
Everything above happens before merge β the reviewer discovers the rules your code follows and
flags a PR that breaks one. Its companion, lenscheck-contract
(a tiny, MIT-licensed runtime library), closes the loop at runtime: your app keeps a declared list
of what each endpoint is allowed to do β write these tables, call these hosts β and can't lie about it. An undeclared DB write or a new external call is blocked (or logged) the moment it happens.
So a rule you confirmed here β "auth before any DB write," "personal data never leaves without auth" β can be
Lenscheck is source-available (Elastic-2.0). Built by Ankush Singh Gandhi. Questions, stars, and sponsorships welcome on GitHub.