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

> Source: <https://dev.to/ankushsinghgandhi/17841-lines-changed-3-things-you-actually-need-to-look-at-1k22>
> Published: 2026-11-16 09:42:19+00:00

*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` 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: **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:

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

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**:

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

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`](//../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`.

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

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](https://github.com/AnkushSinghGandhi/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](https://warriorwhocodes.com). Questions,
stars, and sponsorships welcome on [GitHub](https://github.com/AnkushSinghGandhi/lenscheck-semantic-reviewer).*
