Lenses
On this page
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
Section titled "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
Section titled "Built-in lenses"review-access-controlapp/**review-response-exposureapp/**, inertia/**/*.{ts,tsx,vue}, resources/views/**review-response-designapp/**, inertia/**/*.{ts,tsx,vue}, resources/views/**flow-response-design skill, or a value that many pages pass where one shared value fits.review-cruddy-controllersapp/controllers/**, start/routes.tsflow-cruddy-controllers skill. Its findings are nits.review-migration-safetydatabase/migrations/**review-input-validationapp/**, database/migrations/**review-query-costapp/**review-code-placementapp/**flow-code-placement skill. Its findings are nits.review-testsapp/**, tests/**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
Section titled "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.
# 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.
lenses:
- ref: .flow/lenses/review-money.md
globs: ['app/**', 'database/migrations/**'] A lens with the same name as a built-in one replaces it. To share lenses across apps, see Customizing Flow.
Writing a good lens
Section titled "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
Section titled "Turning a lens off"Remove its entry from .flow/review.yml. The next review runs without it.