Focused Review Lenses

Lenses are domain-expert review passes that run after synthesis in the PR review pipeline. Each lens acts as a specialist reviewer -- a security engineer, a database expert, a concurrency specialist -- applying deep domain knowledge to catch issues that a generalist code review would miss.

Lenses only report issues not already covered by earlier phases. Their findings go through the same filtering, validation, and evidence verification as all other Caliper findings.

Available lenses

security

Reviews code as a security engineer. Catches:

• Injection vulnerabilities -- SQL injection, command injection, XSS, path traversal, template injection
• Auth and authorization bypasses -- missing auth checks, privilege escalation, insecure session handling, JWT misuse, IDOR
• Secrets and credential exposure -- hardcoded secrets, credentials in logs, tokens in URLs
• Input validation gaps -- missing validation at trust boundaries, type confusion
• Insecure data handling -- sensitive data in URLs, unencrypted storage, unsafe deserialization
• Security-sensitive race conditions -- TOCTOU bugs, double-spend patterns

data-integrity

Reviews code as a database and data integrity specialist. Catches:

• Migration safety -- irreversible migrations, missing rollback steps, table-locking migrations, column drops without backup
• Schema consistency -- schema changes not reflected in application code, ORM models out of sync with migrations
• Data loss risks -- DELETE/DROP without confirmation, field truncation, silent data coercion, missing NOT NULL constraints
• Rollback viability -- whether a change can be safely rolled back without orphaned data or broken foreign keys
• Concurrent migration risks -- migrations assuming exclusive table access, missing batching for large updates
• Validation gaps -- schema allowing invalid states, application validation not matching DB constraints

api-contracts

Reviews code as an API design specialist. Catches:

• Breaking changes -- request/response shape changes that break clients, removed fields without deprecation, changed status codes
• Request validation -- missing validation on new parameters, inconsistent validation across similar endpoints
• Response consistency -- inconsistent response envelopes, missing error responses, undocumented status codes, missing pagination
• Versioning concerns -- breaking changes without version bump, mixed API versions in the same module
• Error handling -- generic error responses leaking internals, inconsistent error formats
• Type safety -- runtime types not matching declared types, missing Zod validation at API boundaries

concurrency

Reviews code as a concurrency and distributed systems specialist. Catches:

• Race conditions -- shared mutable state without synchronization, read-modify-write without atomicity
• TOCTOU bugs -- state changing between validation and use (file existence, permission checks, balance checks)
• Async state mutation -- state modified across await boundaries without guards, concurrent promises modifying shared objects
• Lock ordering -- potential deadlocks from inconsistent lock acquisition, missing timeouts on locks
• Resource lifecycle -- resources not released on error paths, connection pool exhaustion from leaked connections
• Retry safety -- non-idempotent operations in retry loops, missing deduplication, side effects in retried operations

design

Reviews code as a software design specialist focused on simplification. Catches:

• Missed abstractions -- repeated patterns across 3+ files that could be a shared function or module
• Factory/framework gaps -- per-file workarounds because the underlying abstraction is incomplete
• Unnecessary complexity -- indirection or wrapper layers that don't provide meaningful value
• Incomplete extractions -- partial adoption of a pattern where some files use a helper and others inline the same logic
• Repeated boilerplate -- sibling files with near-identical structure where differences could be configuration
• Configuration vs. code -- per-file differences that are purely data-driven and should be table-driven

The design lens reviews all files in the PR, not just high/medium-risk files.

Auto-activation

Caliper automatically activates lenses based on risk signals detected during triage. You do not need to configure anything -- if your PR touches auth code, the security lens runs automatically.

File path triggers

Pattern	Lens activated
migrations/ or migration/	data-integrity
schema.prisma	data-integrity
/api/ directory	api-contracts
route.ts, route.js, route.tsx, route.jsx	api-contracts
factory.ts, provider.ts, registry.ts (and .js variants)	design

Diff content triggers

Keywords in changed lines	Lens activated
mutex, semaphore, lock, atomic, Promise.all, Promise.race, Worker	concurrency
auth, session, token, jwt, passport, credential, permission	security
createFactory, createHandler, createProvider, fromConfig	design

Structural triggers

Signal	Lens activated
3+ changed files in the same directory	design

Auto-triggered lenses are merged with any manually configured lenses. Duplicates are removed -- configuring security and having it auto-trigger does not run it twice.

Manual configuration

To always run specific lenses regardless of auto-detection, add them to .caliper/config.yaml:

lenses:
  - security
  - api-contracts

The default configuration includes security, so it runs on every full review even without explicit triggers.

When lenses run

Lenses run only in the full pipeline -- they are skipped on the fast path.

The fast path activates automatically for small PRs (under 100 changed lines, 3 or fewer files, no high-risk files). To control this:

npx caliper 42 --full    # Force full pipeline including lenses
npx caliper 42 --fast    # Force fast path, skip lenses

Within the full pipeline, lenses run after the synthesis phase and before consolidation. All activated lenses run in parallel.

Most lenses review only high and medium-risk files. The design lens is the exception -- it reviews all non-excluded, non-deleted files in the PR, since design issues emerge from looking at the full change set.

Cost implications

Each lens is an additional AI call. The model used depends on PR size:

PR size	Model slot
Small	medium (default: Sonnet)
Normal	medium (default: Sonnet)
Large	large (default: Opus)

A PR that auto-triggers 3 lenses will make 3 additional AI calls on top of the base review, synthesis, consolidation, and narrative phases. Token costs for each lens are tracked and displayed in the review stats footer.

If cost is a concern, you can set lenses: [] in your config to disable the default security lens, relying only on auto-triggered lenses for PRs that genuinely need them. In CI mode, the --max-cost flag provides a hard ceiling.