> [Agent navigation index](/llms.txt)

# Linting and formatting

Brix manages Oxfmt, Oxlint, type-aware linting, and Brix-specific rules as one versioned project
policy. Use `brix format` to write formatting changes and `brix check` to verify formatting, lint,
types, and project structure. Do not install or invoke the underlying tools separately.

For the normal repair loop, run `brix format`, review the diff, then run `brix check`. Reach for
configuration only when the team intends to change policy—not to hide a one-off diagnostic. In a
workspace, make that decision at the root unless a member genuinely owns a separate boundary.

## Keep native configuration files

A standalone project keeps `oxfmt.config.mts` and `oxlint.config.mts` at its root. They call helpers
from the exact installed Brix version, so command-line checks and the official Oxc editor extension
use the same baseline:

`oxfmt.config.mts`

```ts
import { defineBrixOxfmtConfig } from "brix/config";

export default defineBrixOxfmtConfig();

```

`oxlint.config.mts`

```ts
import { defineBrixOxlintConfig } from "brix/config";

export default defineBrixOxlintConfig();

```

Keep these executable native configs. Do not move formatting or lint options into
`vite.config.ts`, replace the helpers with copied defaults, or add legacy `.oxfmtrc.json` and
`.oxlintrc.json` files. Brix maintains the project-local Oxc declarations needed by editors; select
Oxc as the formatter in personal editor settings rather than committing editor preferences for the
team.

`defineBrixOxfmtConfig` accepts native Oxfmt options, appends project ignores after the managed
`**/dist/**`, `**/.brix/**`, `**/styled-system/**`, and `**/src/env.generated.d.ts` ignores, and
preserves project overrides. `defineBrixOxlintConfig`
accepts native Oxlint categories and options; project `rules` merge over managed rules, `jsPlugins`
append without removing Brix's plugin, and project ignores and overrides follow the managed ones.
A top-level project `no-restricted-imports` entry also applies under `src/`: Brix appends its
`paths`, `patterns`, and directly passed restricted paths to the managed import boundaries. Those
boundaries are errors, so a project restriction set to `"warn"` is reported as an error under
`src/`. Do not set that rule in
a project override, because an override's entry replaces the managed boundaries for the files it
matches.
The managed lint ignores also cover generated Panda output, `src/env.generated.d.ts`, and MSW's
generated `mockServiceWorker.js`.

Managed commands select the native config explicitly: the standalone project's own file, or the
nearest member config within its Brix workspace. A missing config is an error, not permission to
inherit a config from an unrelated parent repository. Workspace file-formatting operations also
reject paths outside their root.

This is not complete filesystem isolation. The pinned Oxc tools independently consult ancestor
Git-ignore files, and Oxfmt also reads ancestor `.editorconfig` files. Brix's explicit formatter
defaults override supported EditorConfig properties, but parent Git-ignore rules can still exclude
local files from directory-based formatting or linting.

## Understand the managed lint baseline

The baseline enforces Oxlint's correctness category, type-aware checks, and application
architecture. Any warning fails `brix check` (`maxWarnings: 0`). Under `src/`, it rejects direct
imports of framework-owned dependencies, CommonJS `require()`, Brix test entry points and the
`#brix/test` harness binding in production modules, deployment tooling (`brix/env/upload` and
`brix/artifacts`) in runtime modules, the script environment loader outside `src/env.script.ts`
(`brix/env/script`) and outside scripts and tests (`#brix/env/script`), and parent-relative imports
from `src/features/**`. Tests may import from `brix/test` and `#brix/test`; application
code should use the supported `brix/*` facades. `brix doctor` additionally checks imports, exports,
statically known dynamic imports, and `require()` calls, so lint is not a substitute for diagnosis.

The five anti-slop Brix rules are errors by default:

- `brix/no-unknown-type-aliases` keeps genuinely untrusted values visibly `unknown` until validated.
- `brix/no-widen-then-assert` prevents erasing a known immutable value's type and asserting it back.
- `brix/no-reflect-get` prefers typed property access over `Reflect.get`.
- `brix/no-reflect-apply` prefers typed calls over `Reflect.apply`.
- `brix/no-module-mocking` prevents Vitest or Jest module replacement (`mock`, `doMock`, `setMock`,
  `unstable_mockModule`), including through `brix/test`, `globalThis.vi`, type assertions, and
  `(0, vi.mock)` indirection.

Runtime modules under `src/` use named exports (`import/no-default-export`). Declaration files,
colocated `*.stories.*`, and `*.config.*` tool configs under `__fixtures__/` are exempt; root tool
configs remain free to use required default exports. This also applies to workspace member sources.

Type checking uses the selected TypeScript baseline. The application and React application
baselines include Vite's client declarations, so `import "./app.css"`, `?url` and `?raw` asset
imports, and `import.meta.env` type-check without adding Vite as a project dependency. The library
baseline includes Node's declarations from Brix, so `console`, timers, `URL`, `fetch`, and `node:*`
imports type-check without adding `@types/node`; the UI-library baseline uses DOM declarations
instead. Baselines add these declarations through `files`, so keep an explicit `include` in the
project `tsconfig.json`.

Upstream type-aware rules own promise safety, not method-name matching: `typescript/no-misused-promises`
rejects an async callback passed to synchronous `ResultPromise.tap`; use `tapAsync` instead.
`typescript/no-floating-promises` rejects an unawaited async browser assertion; await the assertion.
The latter comes from the correctness category with the managed TypeScript plugin.
Compile-only `*.test-d.ts` files are exempt from floating-promise checks: their calls test types
without executing asynchronous work. Runtime tests retain the check. Test imports also follow the
[managed Node/browser boundary](/docs/testing-components.md).

`typescript/ban-ts-comment` prohibits `@ts-ignore` and `@ts-nocheck`. A deliberate
`@ts-expect-error` needs a description (at least three characters). Brix does not globally ban
`any`: malformed-input tests and some integration boundaries still need deliberate escape hatches.
The generated `src/env.generated.d.ts` is excluded from lint and formatting: Varlock owns its
suppression header, `brix env types` writes its canonical formatting, and doctor separately verifies that its declarations match the authored environment schema.

Runtime validation, `unknown` boundary parameters, `typeof`, `vi.fn`, and `vi.spyOn` remain valid.
For tests, exercise routes through the [route harness](/docs/testing-routes.md), mock HTTP consumed
by clients with MSW, or use an existing dependency-injection seam instead of replacing a module.

Optional project-policy rules use the same `brix/` prefix: `no-chained-type-assertions`,
`no-conditional-empty-object-spread`, `no-known-value-widening`, `no-object-parameters`,
`no-runtime-typeof`, `no-shape-in-symbol-names`, `no-unknown-parameters`, `no-unknown-returns`,
`no-unsafe-dictionary-type`, and `require-safety-comment-for-type-assertion`. They are not managed
defaults; enable only rules that express a deliberate team policy.

## Configure shared policy and scoped exceptions

Pass native options to the helper. Prefer `overrides` when policy applies only to particular code:

`oxlint.config.mts`

```ts
import { defineBrixOxlintConfig } from "brix/config";

export default defineBrixOxlintConfig({
  rules: { "no-console": "error" },
  overrides: [
    {
      files: ["src/domain/**/*.ts"],
      rules: { "brix/no-unsafe-dictionary-type": "error" },
    },
    {
      files: ["scripts/**/*.ts"],
      rules: { "no-console": "off" },
    },
  ],
});

```

Globs are relative to the config file. A genuine one-statement exception should be narrower than an
override and explain the invariant it preserves:

```ts
// eslint-disable-next-line brix/no-reflect-get -- Preserve the receiver supplied to this proxy accessor.
return Reflect.get(target, key, receiver);

```

`brix/explained-disables` requires ESLint and Oxlint disable comments to use `disable-line` or
`disable-next-line`, name the affected rules, and include `--` followed by a nonempty reason.
File-wide and unnamed disables are rejected, as is any directive naming `brix/explained-disables`.
Because such a directive could suppress the report on itself, files containing one report every
directive problem at line 1 with the offending line in the message. Unused disable directives are
errors as well. This checks the scope and presence of an explanation, not whether the explanation
is truthful. Keep vendored or generated files that start with a file-wide disable in
`ignorePatterns` instead.

Keep regression coverage for such exceptions. Avoid blanket file exclusions and comments that only
claim an assertion or mock is safe. A deliberate project-wide rule change is supported, but turning
off a managed rule globally should be rarer than a local, reasoned exception.

Oxfmt options and ignore patterns follow the same root-relative ownership model:

`oxfmt.config.mts`

```ts
import { defineBrixOxfmtConfig } from "brix/config";

export default defineBrixOxfmtConfig({
  singleQuote: true,
  ignorePatterns: ["generated/**"],
});

```

Use the exact option names supported by the Brix-pinned Oxfmt version. Keep generated output ignored
rather than formatting it by hand.

## Configure a workspace at the root

A workspace root owns `.node-version`, `oxfmt.config.mts`, `oxlint.config.mts`, local Oxc tools,
managed skills, and Git hooks. Members inherit them and should not contain generated copies. Put
shared decisions in the root configs and use workspace-relative globs for member-specific policy:

`oxlint.config.mts`

```ts
import { defineBrixOxlintConfig } from "brix/config";

export default defineBrixOxlintConfig({
  overrides: [
    {
      files: ["apps/admin/src/**/*.ts", "apps/admin/src/**/*.tsx"],
      rules: { "no-console": "error" },
    },
    {
      files: ["packages/generated-contracts/src/**/*.ts"],
      rules: { "brix/no-unknown-type-aliases": "off" },
    },
  ],
});

```

Open the workspace root in the editor so it discovers the shared configs and binaries. Add a member
config only when a tool genuinely needs a separate boundary. A local config replaces ancestor
discovery; it does not automatically extend the root. Keep the Brix helper and explicitly compose
any root options the member must retain. Member `brix init` and workspace upgrades remove only
unchanged generated member configs and matching Node pins; customized files remain untouched.

Root workspace check, format, and verify apply Oxc only to root-owned files, then delegate member
trees to their own phase scripts. A supported member config therefore remains authoritative for
that member instead of being overridden by a second root-config pass. External applications keep
their own formatting and checking scripts; missing external phase scripts are skipped.

Git hook policy likewise belongs only at the Git root under `.brix-hooks/`. `brix hooks enable` and
`brix hooks disable` control dispatch for the current clone. The standard pre-commit hook runs
`brix staged` against the exact index without rewriting unstaged work. The dispatcher skips a
policy file that is not executable; `brix hooks status` lists such policies and reports the
dispatcher as `installed (N inactive hooks)` rather than `healthy` until you run `chmod +x` on them.

## Run and repair checks

```sh
brix format
brix check
brix doctor
brix hooks status
brix staged

```

Format first, review the diff, and stage the intended result. `brix check` never applies formatter or
linter fixes. In a workspace, root commands cover all members; focused commands such as
`brix check#checkout-bff` select one project while still preparing its shared libraries. Hooks are
early feedback only—`brix verify` and CI remain authoritative.

Continue with [project structure](/docs/project-structure.md), [testing](/docs/testing.md), and
[workspaces](/docs/workspaces.md).
