Dev.to WebDev πŸ›  Dev πŸ‘ 0 πŸ“– 26 min read

17,841 Lines Changed. 3 Things You Actually Need to Look At.

πŸ“ŒLenscheck: See What a Pull Request Actually Changes β€” On Every Repo You Own 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 rev

17,841 Lines Changed. 3 Things You Actually Need to Look At.

πŸ“ŒLenscheck: See What a Pull Request Actually Changes β€” On Every Repo You Own

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

πŸ“ŒTable of contents

  • Quickstart (60 seconds)
  • What is Lenscheck (in one minute)
  • Two features, two problems (start here)
  • Install
  • Three ways to use Lenscheck
  • The Web UI, panel by panel
  • The CLI, command by command, flag by flag
  • Every feature explained
  • The GitHub Action, input by input
  • Set up Lenscheck for all your repos (personal, team, or org)
  • A full worked example
  • Honesty rules (why Lenscheck never lies)
  • Quick reference card
  • Glossary (words you need to know)

πŸ“ŒQuickstart (60 seconds)

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.

πŸ“Œ1. What is Lenscheck (in one minute)

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."

The Lenscheck landing page

πŸ“Œ2. Two features, two problems

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.

πŸ”½1) See what a PR means β€” not just what changed

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.

πŸ”½2) Enforce the rules your code already follows β€” invariants

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
it ships.

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.

πŸ“Œ3. Install

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

πŸ“Œ4. Three ways to use Lenscheck

You can use Lenscheck in whichever way fits:

  1. Web UI β€” run lenscheck serve, open your browser, click around. Best for exploring and for people who don't live in the terminal. β†’ jump to the tour
  2. Command line β€” lenscheck review …. Best for scripts, quick checks, and CI. β†’ jump to the CLI
  3. GitHub Action β€” Lenscheck runs automatically on every PR and comments on it. Best for teams. β†’ jump to the Action

They all share the same engine, so they find the same things.

πŸ“Œ5. The Web UI, panel by panel

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.

The top bar β€” choosing what to review

A finished review in the web UI

Along the top you pick what to compare. You have four ways:

  • PR β€” pick a merged Pull Request from the dropdown and hit Review.
  • branches β€” compare two branches (e.g. main β†’ my-feature).
  • commits β€” compare two commits.
  • Branch vs default button β€” the one-click shortcut: review your current branch against the main branch. (This is the zero-arg default.)

Reading a review (top to bottom)

Once a review runs, you read it top-to-bottom. Using the screenshot above:

  1. 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)

  2. 🎭 Intent vs. behavior β€” the red panel. The PR called itself a "refactor / no behavior
    change,"
    but Lenscheck found it added an endpoint and started logging an email. When the
    promise and the facts disagree, this panel calls it out. (intent vs. behavior)

  3. πŸ“¦ Dependency capability changes β€” bumped libraries and whether the new version can do more
    than the old one. (dependency scanning)

  4. The tally β€” πŸ”΄ 1 β€” how many findings at each severity.

  5. The change list (left) β€” one row per changed endpoint, worst first. Click a row to see…

  6. 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.

  7. 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.

The "Where to look" tab β€” every fact at its exact line

Click any block in the graph (or a line here) and Lenscheck shows you the source, with the exact
line highlighted:

Click a block to see its source, the exact line highlighted

The Invariants panel β€” teach Lenscheck your rules

Click βš– Invariants in the top bar:

The invariants panel: discover, confirm, blame

Lenscheck samples your git history and shows candidate rules it noticed your codebase following. In
the screenshot:

  • "External/PII egress limited to 2 known destinations" [boundary] β€” holds 2/2 (100%). It's the rule that makes the ExportUsers change dangerous: the new endpoint would send an email to a third destination, widening that boundary.
  • Each rule has a Confirm button (freeze it as a rule Lenscheck will enforce from now on); rules with exceptions also get a 🩸 Blame button (find the commit that first broke it).

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).

Handy web tricks

  • 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.

πŸ“Œ6. The CLI, command by command

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.

 raw `lenscheck review` endraw  in the terminal

The same review as a self-contained HTML file (--html) you can send to anyone β€” no install
needed:

The self-contained HTML report β€” what changed, how it flows, where to look

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 β€” the web UI

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 on 0.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; default HOST is 0.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: confirm Β· fix (confirm, but the current
exceptions are bugs) Β· skip Β· quit.

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:

The digest posted to Slack

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.

πŸ“Œ7. Every feature explained

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.

A diff shows text, not meaning

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).

Your codebase rules are not enforced

Invariants: discover, confirm, enforce, blame β€” headline feature β‘‘. The compounding asset. Four steps:

  1. Discover (lenscheck invariants) β€” mine history for rules your code already follows:
   ⚠ 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)
  1. Confirm (lenscheck invariants --confirm, or the web button) β€” mark the ones that are real. Saved
    to a rules file. No JSON editing.

  2. Enforce (lenscheck review --invariants rules.json) β€” every future PR that breaks a confirmed
    rule gets a πŸ”΄, and --fail-on violation can block the merge.

  3. 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.

You still have to read the whole PR

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.

The PR description contradicts the code

Intent vs. behavior. Your PR title/description is a promise. Lenscheck checks it against the facts.

  • Says "refactor / no behavior change" but added an endpoint or a DB write β†’ πŸ”΄ "claims refactor, but behavior changed here."
  • Says "docs only" but code changed β†’ flagged.

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

Is it a real leak, or a coincidence?

PII taint β€” the precision feature. Old tools say "personal data and an external call are both in
this function β€” maybe it leaks."
Vague. Lenscheck follows the data:

  • If an email actually flows into an external call / log / response β†’ βœ… verified: email β†’ requests.post @ line 46. The exact field, the exact exit, the exact line.
  • If they just co-exist with no traced path β†’ it stays ⚠ potential (honest, no false alarm).
  • If the data passes through a function Lenscheck doesn't recognize (which might clean it) β†’ it refuses to call it a confirmed leak.

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>.

A dependency bump quietly gains new powers

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 newly gained powers:

  • 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.

The dependency capability panel β€” bumped packages, honest about the unresolved ones

A text list does not show the flow

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:

The Mermaid flow diagram as GitHub renders it in the PR comment

The finding is not next to the code

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
rejects anything else); the rest roll into the one sticky summary comment.

A queue of PRs is hard to triage

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.

Findings belong in the Security tab

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.

A review should not need arguments

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.

πŸ“Œ8. The GitHub Action, input by input

Add this workflow and Lenscheck reviews every PR automatically:

# .github/workflows/lenscheck.yml
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 repos without 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).

πŸ“Œ9. Set up Lenscheck for all your repos

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.

Step 1 β€” Put the workflow in one central repo

Make a repo β€” call it lenscheck-workflows (under your username or org) β€” and add the real workflow
there once, as a reusable workflow:

# lenscheck-workflows/.github/workflows/lenscheck.yml
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:

# any-repo/.github/workflows/lenscheck.yml
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.

Step 2 β€” Start in "observe mode" (comment, never block)

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.

Step 3 β€” Turn on your rules (the moat), everywhere, 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 no new external destination for personal data β€” and every repo inherits them. Commit
each repo's lenscheck-invariants.json, and the workflow enforces it from then on.

Step 4 β€” Get one number across all your repos (optional)

Per-PR comments help whoever's on that PR. For the big picture β€” how many risky PRs are open
right now
β€” lenscheck digest counts the open PRs carrying each 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.)

Step 5 β€” Start blocking merges β€” last, and only on the sure things

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.

One security note before you go wide

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
place. And to reassure any security reviewer: Lenscheck never runs your code β€” it reads it with
Python's parser and analyzes clean git snapshots, so there's nothing to execute.

πŸ“Œ10. A full worked example

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:

  • adds POST /api/users/export with no login required (AllowAny),
  • inside it, writes to the AuditLog table and sends a user's email to an external webhook,
  • and changes GET /api/profile to log the user's email,
  • while bumping requests and six.

Run it:

lenscheck review /path/to/repo --commit <sha> --sarif out.sarif

Lenscheck produces, in one pass:

  • Summary: "adds 1 endpoint, 1 new DB write to AuditLog, 1 new external call… and 4 new PII signals."
  • 🎭 Contradiction: "claims refactor, but adds an endpoint" and "…but new PII signal: email β†’ log.info."
  • πŸ”΄ NEW ENDPOINT api/users/export: "new endpoint exposes a PII path with open/unspecified auth" β€” with the verified leak email β†’ requests.post @ shop/views.py:46.
  • πŸ“¦ Dependencies: the two bumps (with capabilities, or ⚠ offline).
  • πŸ”€ Flow diagram: the Mermaid picture above.

Every single item points to a line you can click. Nothing was guessed.

πŸ“Œ11. Honesty rules

Lenscheck's whole value is that you can trust it. So it follows strict rules:

  • Never render "not observed" as "doesn't exist." If Lenscheck can't follow something, it shows ⚠ or ? β€” never a false all-clear.
  • A "verified" finding is really verified. The PII taint only says βœ… when it saw the whole path; if data might have been sanitized, it stays ⚠.
  • No arbitrary file writes, no surprise network. The web "Confirm" only writes the file you configured; dependency scanning can be turned off.
  • Every number traces to a file:line. Because Lenscheck reports facts, not vibes.

πŸ“Œ12. Quick reference card

# review
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

# post to a PR
lenscheck post 123 pr_review.md --json pr_review.json --inline --label
lenscheck post 123 pr_review.md --dry-run          # preview, no posting

# web UI
lenscheck serve                                    # this repo
lenscheck serve --repo . --invariants rules.json   # + enable Confirm buttons

# invariants (rules)
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

# digest (org-wide roll-up for leadership)
lenscheck digest --org my-org                       # open PRs by lenscheck:* label
lenscheck digest --org my-org --repos repos.txt --slack "$SLACK_WEBHOOK"  # + adoption, to Slack

# env vars
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

πŸ“ŒGlossary (words you need to know)

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:

  • πŸ”΄ critical β€” security / data-flow (e.g. an open endpoint writing to the DB)
  • 🟠 high β€” money paths (payments, orders)
  • 🟑 medium β€” a new write or a dependency change
  • 🟒 low β€” a safe refactor, nothing risky

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
that matters.

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.

πŸ“ŒCompanion tool: lenscheck-contract

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 declared once and enforced in production, not just checked in review. Same
promise, two moments: the reviewer catches it in the PR; the contract stops it in prod. β†’
Read the contract guide.

Lenscheck is source-available (Elastic-2.0). Built by Ankush Singh Gandhi. Questions,
stars, and sponsorships welcome on GitHub.

πŸ“° Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.