# Inspect

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

## Overview

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.

## Starting an inspection

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.

## What an inspection reads

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.

```sh
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>
```

::::field-group

:::field{name="route" type="method 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.
:::

:::field{name="command" type="command name"}
The command's `prepare`, `interact`, `run` and `completed` methods, in that order, for each one the command defines.
:::

:::field{name="job" type="class 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.

## The data loading lens

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

## Findings

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 often                   | Cost grows with the rows | Cost stays the same |
| --------------------------- | ------------------------ | ------------------- |
| On every run                | major                    | minor               |
| Under production conditions | major                    | minor               |
| Only in rare cases          | minor                    | nit                 |

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](/docs/flow/reviews/configuration#accepting-a-finding).

```ts
// 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)
```

## Writing your own inspection lens

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](/docs/flow/reviews/lenses#writing-your-own-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.

## Next steps

::card-group
:::card{title="Code reviews" to="/docs/flow/reviews/introduction"}
Review the changes in a pull request, on your computer or on GitHub.
:::

:::card{title="Customizing Flow" to="/docs/flow/customizing"}
Add your own docs, skills and lenses.
:::
::
