---
summary: The lint rules Flow ships, how to turn them on, and what each rule checks.
---

# Lint rules

Your agent reads Flow's instructions, but nothing guarantees it follows them every time. When a convention can be checked in the code itself, Flow ships it as an [ast-grep](https://ast-grep.github.io/) rule that ESLint runs. ESLint reports a violation no matter who wrote the code, in your editor, in `npm run lint` and in CI, so you never have to remind your agent about it.

## Turning the rules on

`npx @adonisplus/flow install` offers to add the rules to your `eslint.config.js`. It installs `@adonisjs/eslint-ast-grep` and adds two lines to the config.

```js [eslint.config.js]
import { configApp } from '@adonisjs/eslint-config'
import { astGrep } from '@adonisjs/eslint-ast-grep' // [!code ++]

export default configApp(...astGrep('@adonisplus/flow/rules')) // [!code ++]
```

If you use a different ESLint config, Flow prints these two lines so you can add them yourself.

## Switching a rule off

Each rule is named `ast-grep/<rule>`. To switch a rule off for one line, use an ESLint comment.

```ts
// eslint-disable-next-line ast-grep/no-top-level-functions
function legacyHelper() {}
```

To switch it off for the whole app, set it to `off` in your config.

```js [eslint.config.js]
export default configApp(...astGrep('@adonisplus/flow/rules'), {
  rules: { 'ast-grep/no-top-level-functions': 'off' },
})
```

## no-top-level-functions

AdonisJS apps keep their behaviour in classes. A class can receive its dependencies through the container with `@inject()`, and a test can swap them with `app.container.swap()`. A top-level function imports its dependencies directly. Functions also have no natural home, so they collect in `utils` and `helpers` files. This rule keeps one way of writing behaviour, so your agent never has to choose between a function and a class.

Reports functions declared at the top level of a file. Move the code into a method on a class. The `flow-code-placement` skill helps your agent pick the class.

It checks the TypeScript files of your backend. It skips `inertia/`, `resources/`, `tests/`, `bin/`, `*.config.ts` files and `.d.ts` files.

## exported-functions-are-factories

An exported function is a top-level function that the rest of your app depends on, so the same reasoning applies. The exception is a factory: a function named `create…` or `make…` that builds and returns a class instance, such as a helper that sets up a configured client. A factory gives callers a short way to get an instance, while the behaviour stays in the class it returns. Mixins in `mixins/` are not checked, because a mixin is a function by design.

Reports exported functions, unless the name starts with `create` or `make` and the function returns a class instance. Turn the function into a factory, or move the code into a method on a class.

It checks the TypeScript files of your backend. It skips `inertia/`, `resources/`, `tests/`, `bin/`, `mixins/`, `*.config.ts` files and `.d.ts` files.

## no-private-controller-methods

A controller maps an HTTP request to your app: it reads the input, calls your models and services, and returns a response. A private method on a controller holds a step outside that job, usually a query, a calculation or a rule of your domain. Inside the controller, that step can't be used by a command, a job or another controller, and a test can only reach it through an HTTP request. Put it on a model, a service or a pattern object, where any part of your app can use it and test it. A protected method leads to base controllers that actions inherit from, so the rule reports it too.

Reports private and protected methods on controllers. Write the steps inside the action, or move them to the place the `flow-code-placement` skill suggests.

It checks the files in `controllers/`.

## types-live-in-types-directory

This rule keeps types and interfaces in the `types` directory, so your runtime files only contain code that runs. Every type has one place to import from, and a file that needs only a type never imports a service or a controller to get it, which avoids circular imports. AdonisJS packages follow the same convention and keep their types in separate files. Validators and value objects are not checked, because their types come from their own code.

Reports types and interfaces declared outside the `types` directory. Move the declaration to `types/` and import it with `import type`.

It checks the TypeScript files of your backend. It skips `types/`, `validators/`, `values/`, `inertia/`, `resources/`, `tests/` and `.d.ts` files.

## no-shared-mutable-test-state

A variable that several tests change makes those tests depend on each other. To understand one test, you have to read every test that reads or changes the variable. Declaring the variable inside the test gives each test its own data.

Reports `let` and `var` declarations outside a test callback. Declare the variable inside the test, or use `const` if the value never changes.

It checks the files in `tests/`.

## test-files-contain-tests

A test file defines tests and nothing else. When a test needs a helper, the helper comes from `tests/helpers/`. Test code and helper code stay in separate files, and every helper is in one place where you can find and reuse it.

Reports exports, reusable functions and classes, and named types in test files. Move reusable code to `tests/helpers/` and named types to `tests/helpers/types.ts`. Values and functions defined inside a single test are fine.

It checks the files in `tests/`, except `tests/helpers/` and `tests/bootstrap.ts`.

## test-helpers-contain-runtime-code

Test helpers contain code that runs. Types used by your tests go in `tests/helpers/types.ts`, which is the same split that `types-live-in-types-directory` applies to your app.

Reports types and interfaces declared in test helpers. Move them to `tests/helpers/types.ts` and import them with `import type`.

It checks the files in `tests/helpers/`, except `tests/helpers/types.ts`.

## playwright-locators-are-exact

By default, Playwright matches a text locator against any element that contains the text. A locator for "Sign in" also matches "Sign in with a passkey", so a test can click the wrong button and still pass. Setting `exact` on every text locator makes each one say which match it means.

Reports Playwright text locators that don't set the `exact` option. Pass `{ exact: true }`, or `{ exact: false }` when you want a partial match. Without it, a "Sign in" locator also matches "Sign in with a passkey".

It checks the files in `tests/`.
