This guide covers inspecting a single entry point of your app. You will learn:

  • What an inspection catches that a code review misses
  • How to start an inspection
  • Which steps of a route, command or job an inspection reads
  • What the data loading lens reports, and how findings are graded
  • How to write your own inspection lens

A code review only reads the lines a change adds or modifies. Some problems don't live in any single change. They come from the whole path of a request. For example, a middleware loads the current workspace onto ctx, the controller loads it again, and a shared prop in the Inertia middleware loads it a third time. Each file looks fine on its own.

An inspection reads one entry point of your app from start to finish: a route, an Ace command or a queue job. Flow first lists every step that runs, in order. Then each inspection lens reads the whole path, following each call into your services, models, validators, policies, transformers and page props, and reports the problems it finds.

An inspection never changes your code. Run it on a slow page, before you ship a new feature, or on older code you want to clean up.

Ask your coding agent to inspect an entry point, either in your own words or with the exact route. The flow-inspect skill works out which entry point you mean.

Inspect the members page of a workspace
Inspect GET /w/:slug/members

The skill matches your words against the routes from node ace list:routes --json, the commands from node ace list --json, and the classes that extend Job in the locations of config/queue.ts. If more than one entry point matches, it stops and prints each one as a request you can send again. If nothing matches, it suggests the closest ones.

Since the skill runs node ace, your app must boot in the terminal, for example with a complete .env file.

Before any lens runs, the skill calls the inspect-plan command. It prints the steps of the entry point as JSON, in the order they run. Each step is one method in one file. You can run it yourself to see exactly what an inspection covers.

Terminal
npx @adonisplus/flow inspect-plan route GET /w/:slug/members
npx @adonisplus/flow inspect-plan command <command name>
npx @adonisplus/flow inspect-plan job <class name>
routemethod and pattern
The server.use and router.use middleware from start/kernel.ts, then the route's named middleware, then the controller method. When the controller method calls inertia.render, the share method of the Inertia middleware comes last, because shared props are resolved after the handler. For a route with a closure handler, the closure is the last step.
commandcommand name
The command's prepare, interact, run and completed methods, in that order, for each one the command defines.
jobclass name
The job's execute and failed methods, for each one the job defines.

Code that the inspection does not read is listed under skipped, with the reason: middleware or a controller from a package, a closure middleware, a command from a package, or a # import that no imports entry in package.json matches. A lens reads only the method of each step and the code that method calls, never the other methods in the same file.

Flow ships one inspection lens, inspect-data-loading. It looks at every data call, meaning any read from a database, a cache, a file or an external service. Validation rules that query the database, such as exists and unique, count as data calls too. The lens reports:

  • Duplicates: two data calls fetch the same data with the same filter.
  • Refetches: a data call fetches data the entry point already has, for example on ctx, in auth.user, in a variable or in a loaded relation.
  • Overfetching: a data call fetches more rows than the code needs, for example when the code filters the rows after the query. Selecting columns that no code reads does not count.
  • Per-row calls: a data call runs once for every item in a loop. The loop is often hidden in a transformer, a model hook or a policy, since each of those runs once per row.

It ignores two reads of the same rows when one takes a lock or runs inside a transaction and the other doesn't. It also ignores a read that follows a write to the same data. Each finding suggests a fix based on the harness docs, for example a relation to preload or a value to keep on ctx.

The skill reopens the file behind each finding and drops any claim the code doesn't back up. When two lenses report the same problem, it merges them into one finding. It then grades each finding by its cost and by how often it happens.

How oftenCost grows with the rowsCost stays the same
On every runmajorminor
Under production conditionsmajorminor
Only in rare casesminornit

Production conditions are things like a large table or input that any user can send. Rare cases are things like a race between two requests or a user with one specific role.

The agent prints the findings in its session, most severe first, each with its file and line, the problem, the impact and the fix. An inspection with no findings is a valid result.

If you break a rule on purpose, put a flow-allow comment directly above the line or block. Name the doc or lens whose rule the code breaks, and explain why it has to. The inspection then drops that finding. See Accepting a finding.

// flow-allow inspect-data-loading: a webhook can change the balance during the request, so read it again
const balance = await Balance.findOrFail(workspace.balanceId)

An inspection runs every .flow/lenses/inspect-*.md file. Add your lens to .flow/custom/lenses/ with a name that starts with inspect-, then run npx @adonisplus/flow install. The next inspection picks it up. You don't need to add it to .flow/review.yml.

An inspection lens has the same sections as a review lens: Scope, Method, Threshold and Reporting. The difference is that its Method works on the steps of the plan rather than on changed lines.

Inspection lenses can't run in a code review. If .flow/review.yml lists a lens whose name starts with inspect-, the review fails with an error.

The skill runs each lens in its own sub-agent, all at the same time. Coding agents that can't start sub-agents run the lenses one after another.

Code reviews

Review the changes in a pull request, on your computer or on GitHub.

Customizing Flow

Add your own docs, skills and lenses.