# Lenses

This guide covers the lenses of a Flow code review. You will learn:

- What each built-in lens checks
- How to write a lens of your own
- How to turn a lens off

## Overview

A lens is one focus of a code review, such as access control or query cost. A review runs every lens over the changed files that match its globs, each in its own sub-agent. A lens grades each finding critical, major, minor or nit, from what the defect can cause and how likely it is.

`.flow/review.yml` lists the lenses that run. `npx @adonisplus/flow install` writes it with the built-in lenses and their default globs.

## Built-in lenses

::::field-group

:::field{name="review-access-control" type="app/**"}
A changed action that reads or changes another user's record, or acts on a record without an authorization check.
:::

:::field{name="review-response-exposure" type="app/**, inertia/**/*.{ts,tsx,vue}, resources/views/**"}
A private value sent to the client, an error that tells more than it should, a secret in a cookie that is not encrypted, or a private page that a cache or the browser history keeps.
:::

:::field{name="review-response-design" type="app/**, inertia/**/*.{ts,tsx,vue}, resources/views/**"}
A response that breaks the rules of the `flow-response-design` skill, or a value that many pages pass where one shared value fits.
:::

:::field{name="review-cruddy-controllers" type="app/controllers/**, start/routes.ts"}
A controller or route that breaks the rules of the `flow-cruddy-controllers` skill. Its findings are nits.
:::

:::field{name="review-migration-safety" type="database/migrations/**"}
A migration that can lose data, fail on a table with rows, break the code that runs during the deploy, or lock a large table.
:::

:::field{name="review-input-validation" type="app/**, database/migrations/**"}
Input from a request, a webhook or a job that reaches the code without a validator, or a check in the wrong layer.
:::

:::field{name="review-query-cost" type="app/**"}
An N+1 query, a read of every row of a growing table, or a connection held while the code waits on something else.
:::

:::field{name="review-code-placement" type="app/**"}
Server code that breaks the rules of the `flow-code-placement` skill. Its findings are nits.
:::

:::field{name="review-tests" type="app/**, tests/**"}
A changed behaviour with no test that proves it, or a test that breaks the rules of the `flow-design-tests` skill.
:::

::::

Each lens reads the files after its name by default. `review-response-exposure` and `review-response-design` have a version for each stack, and the installer picks the one of your app.

## Writing your own lens

A lens is a Markdown file with four sections: Scope, Method, Threshold and Reporting. Put yours in `.flow/custom/lenses/` and commit it.

The following is a simple example, but it covers all the sections a lens must have.

````md [.flow/custom/lenses/review-money.md]
# Review lens: Money

## Scope

- **Amounts** Whether changed code stores or computes an amount of money as a float.

## Method

Read each changed model, migration and service that handles a price, a total or a balance.

## Threshold

Report a finding when an amount is a `float` or a `decimal` column, or when code divides or multiplies an amount without rounding it to cents.

## Reporting

- Name the column or the line, and the amount it holds.
- State the fix: store cents in an integer column, and round once, where the amount is shown.
````

Run `npx @adonisplus/flow install` to copy it next to Flow's lenses. Then add it to `.flow/review.yml`, with the files it reads.

```yaml [.flow/review.yml]
lenses:
  - ref: .flow/lenses/review-money.md # [!code ++]
    globs: ['app/**', 'database/migrations/**'] # [!code ++]
```

A lens with the same name as a built-in one replaces it. To share lenses across apps, see [Customizing Flow](/docs/flow/customizing).

### Writing a good lens

- Give a lens one focus. A lens that overlaps a built-in one reports the same findings twice.
- Write each Scope item as a question about the change, and name the defect, like "Whether changed code stores an amount of money as a float."
- In Threshold, say when to report, and list what not to report. Without that list, a lens reports noise.
- In Reporting, ask for the defect, what it costs, and the fix.
- Reviews are not deterministic. Do not change a lens because one review missed one finding. Change it for a gap you see again and again.

## Turning a lens off

Remove its entry from `.flow/review.yml`. The next review runs without it.

## Next steps

::card-group
:::card{title="Configuration" to="/docs/flow/reviews/configuration"}
The settings of `.flow/review.yml`.
:::

:::card{title="Customizing Flow" to="/docs/flow/customizing"}
Your own docs, skills and lenses, and sharing them across apps.
:::
::
