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

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.

review-access-controlapp/**
A changed action that reads or changes another user's record, or acts on a record without an authorization check.
review-response-exposureapp/**, 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.
review-response-designapp/**, 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.
review-cruddy-controllersapp/controllers/**, start/routes.ts
A controller or route that breaks the rules of the flow-cruddy-controllers skill. Its findings are nits.
review-migration-safetydatabase/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.
review-input-validationapp/**, 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.
review-query-costapp/**
An N+1 query, a read of every row of a growing table, or a connection held while the code waits on something else.
review-code-placementapp/**
Server code that breaks the rules of the flow-code-placement skill. Its findings are nits.
review-testsapp/**, 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.

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.

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

.flow/review.yml
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.

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

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

Configuration

The settings of .flow/review.yml.

Customizing Flow

Your own docs, skills and lenses, and sharing them across apps.