@jameswyse/oxc-config 0.1.0 → 0.3.0

package/README.md

@@ -2,204 +2,71 @@
 
 Opinionated [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) and [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) configs for TypeScript and JavaScript projects. They combine Oxlint's native rules with custom rules for type and data safety, comment-free code, configuration ownership, import boundaries, server-action guards, test reliability and statement spacing.
 
-The rules aim to keep both people and coding agents on the same standards: parse external data at the seam, use named exports, never ship console logging, and let names, types and tests carry intent instead of comments. [The reference](REFERENCE.md) maps each standard to its rules and states what lint cannot check.
+The rules aim to keep both people and coding agents on the same standards: parse external data at the seam, use named exports, never ship console logging, and let names, types and tests carry intent instead of comments. [The reference](REFERENCE.md) maps each standard to its rules.
 
-Requires Node.js 22.23 or later. Supports Oxlint 1.86 or later, Oxfmt 0.71 or later and oxlint-tsgolint 7.0.2003 or later, within their current major versions.
+## Example: a test that can't fail
 
-## Install
-
-```sh
-pnpm add -D @jameswyse/oxc-config oxlint oxfmt oxlint-tsgolint
-```
-
-The React profile uses `eslint-plugin-react-you-might-not-need-an-effect`, which declares an ESLint peer even though it runs under Oxlint. To skip installing ESLint with pnpm, add this to the project's `pnpm-workspace.yaml` before installing:
-
-```yaml
-autoInstallPeers: false
-peerDependencyRules:
-  ignoreMissing:
-    - eslint
-```
-
-`autoInstallPeers` affects every dependency in the workspace. No ESLint configuration is needed either way.
-
-## Configure
-
-Create `oxlint.config.ts` in the project root:
+Coding agents often write tests that pass whatever the code does. This one passes as long as `parseUser` is exported:
 
 ```ts
-import { createLintConfig } from "@jameswyse/oxc-config/oxlint";
-
-export default createLintConfig();
-```
-
-Type-aware checking is on by default. It needs the project's `tsconfig.json` and `oxlint-tsgolint`, which uses TypeScript 7. Configurations that rely on removed options such as `baseUrl` need migrating first. For plain JavaScript or a TypeScript project that is not yet compatible, pass `typeAware: false`. Syntax and scope rules still run, and explicit `any` is still rejected.
-
-Create `oxfmt.config.ts` beside it:
-
-```ts
-import { formatConfig } from "@jameswyse/oxc-config/oxfmt";
-
-export default formatConfig;
+test("parseUser", () => {
+  expect(parseUser).toBeDefined();
+});
 ```
 
-Add the scripts:
-
-```json
-{
-  "scripts": {
-    "lint": "oxlint .",
-    "lint:fix": "oxlint --fix . && oxfmt . && oxlint .",
-    "format": "oxfmt .",
-    "format:check": "oxfmt --check ."
-  }
-}
+```text
+error wyse(no-edit-proof-assertions): This assertion only proves that an import exists or that a value is a function. Call it and assert the behaviour it provides.
 ```
 
-Errors fail the run. Warnings mark patterns worth reviewing that have legitimate uses, so they report without blocking: dependency cycles, barrel and forwarding modules, `typeof` outside type guards, swallowed errors, boolean parameters on exported functions, pass-through functions, tests without a matching owner file and test timeout overrides. `lint:fix` formats after applying lint fixes, then lints again to confirm the result.
-
-## Select framework and runtime profiles
-
-Enable only the tools the project uses. Each profile accepts `true` for its default scope or an array of project-relative globs. `nextjs` takes application root directories instead of globs.
+Calling the function and checking its result passes:
 
 ```ts
-import { createLintConfig } from "@jameswyse/oxc-config/oxlint";
-
-export default createLintConfig({ react: true, vitest: true });
-```
-
-For a monorepo with separate server and browser packages:
-
-```ts
-import { createLintConfig } from "@jameswyse/oxc-config/oxlint";
-
-export default createLintConfig({
-  nextjs: ["apps/web"],
-  react: ["packages/ui/**/*.{ts,tsx}"],
-  node: ["packages/server/**/*.ts"],
-  vitest: ["**/*.{test,spec}.{ts,tsx}"],
+test("parseUser reads the name from JSON", () => {
+  expect(parseUser('{"name":"Ada"}')).toEqual({ name: "Ada" });
 });
 ```
 
-| Option     | Adds                                                                                                                                                                    |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `react`    | React and React Compiler rules, accessibility rules, effect-misuse rules, and e18e performance rules outside tests                                                      |
-| `nextjs`   | The React profile plus Next.js rules, with default exports allowed for `app` and `pages` entrypoints under each root                                                    |
-| `node`     | Node.js environment and rules                                                                                                                                           |
-| `vitest`   | Vitest rules; its globs join the shared test scope                                                                                                                      |
-| `jest`     | Jest rules; keep its scope separate from Vitest when both exist                                                                                                         |
-| `effect`   | Effect error-tag and service-import rules, for modules that use [Effect](https://effect.website)                                                                        |
-| `tests`    | Extra test globs, such as Playwright or Node tests, for the custom test rules                                                                                           |
-| `electron` | Electron security rules everywhere, and an import boundary keeping `electron` and `node:*` out of the renderer (`src/renderer/**` by default, or `{ renderer: [...] }`) |
-
-Default exports are also accepted where a tool loads them: config files, Storybook stories and `.storybook`, `sanity.cli`, GraphQL Codegen entrypoints and declaration files.
+This is one rule of many. [The reference](REFERENCE.md) lists the rest, from unparsed external data and scattered `process.env` reads to server actions that skip their auth check.
 
-In a monorepo, run Oxlint from each package with a `tsconfig.json`, or pass an existing lint tsconfig with `--tsconfig`.
+## Set up with a coding agent
 
-## Enforce project boundaries
-
-These options need the project to name its owners, so each is off until configured. Globs are relative to the directory Oxlint runs from.
-
-```ts
-import { createLintConfig } from "@jameswyse/oxc-config/oxlint";
+Give the agent this prompt:
 
-export default createLintConfig({
-  react: ["src/renderer/**"],
-  env: ["src/main/config.ts", "src/renderer/env.ts"],
-  boundaries: [
-    {
-      files: ["src/renderer/**"],
-      deny: ["electron", "node:*", "@main/**", "src/main/**"],
-      message: "Use the typed contextBridge API exposed by the preload process.",
-    },
-  ],
-  serverActionGuards: ["requireStaffPermission", "requireMember"],
-  clock: ["src/platform/clock.ts"],
-  random: ["src/platform/ids.ts"],
-});
+```text
+Set up @jameswyse/oxc-config in this repository by following
+https://github.com/jameswyse/oxc-config/blob/main/docs/agent-setup.md
 ```
 
-- `env` lists the modules that may read `process.env` or `import.meta.env`. Other source files must receive parsed configuration. Config files and scripts are entrypoints and remain allowed.
-- `boundaries` rejects imports from `files` that match a `deny` glob. Bare specifiers match as written. Relative specifiers resolve to a project path first, so `../main/ipc` matches `src/main/**`. Type-only imports are allowed because they are erased. Use `ignore` to exclude files from a boundary's scope.
-- `serverActionGuards` requires every exported function in a `"use server"` module, and every inline `"use server"` function, to start by awaiting one of the named guards. Server-action modules must export each action where it is declared. A guard's name cannot prove it authorises the operation, so review the guard itself.
-- `clock` and `random` list the modules that may read the current time (`Date.now()`, argument-less `new Date()`) or generate random values and IDs (`Math.random()`, `crypto.randomUUID()`, `randomUUID`/`randomInt` from `node:crypto`). Other production code must receive them, so tests can control them without faking globals. Test files, parameter defaults such as `now = new Date()` and passing `Date.now` uncalled are allowed. Durations from `performance.now()` and secret generation are out of scope.
+## Set up by hand
 
-## Share strict compiler settings
+Install the package and its peers. It requires Node.js 22.23 or later.
 
-The package exports `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride` and `noFallthroughCasesInSwitch` as a base config. Extend it from the project's `tsconfig.json` and keep target, module and path settings local:
-
-```json
-{
-  "extends": "@jameswyse/oxc-config/tsconfig"
-}
+```sh
+pnpm add -D @jameswyse/oxc-config oxlint oxfmt oxlint-tsgolint
 ```
 
-In an existing project, `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` usually surface many type errors, so adopt them as a separate migration.
-
-## Add project-specific exceptions
-
-Append overrides to the returned config so its framework and test overrides stay active. Oxlint applies file overrides after top-level `rules`, so type-aware and framework rules can only be changed by a later override.
+Create `oxlint.config.ts` and `oxfmt.config.ts` in the project root:
 
 ```ts
 import { createLintConfig } from "@jameswyse/oxc-config/oxlint";
 
-const base = createLintConfig({ react: true, vitest: true });
-
-export default {
-  ...base,
-  ignorePatterns: [...base.ignorePatterns, "src/routeTree.gen.ts"],
-  overrides: [
-    ...base.overrides,
-    {
-      files: ["src/validation/**/*.ts"],
-      rules: {
-        "wyse/no-runtime-typeof": "off",
-        "wyse/no-unsafe-dictionary-type": "off",
-      },
-    },
-  ],
-};
+export default createLintConfig();
 ```
 
-Use this for validated input seams, real timer tests, external module mocks, framework-required default exports and generated files. Keep each exception to the smallest scope. Suppression comments that no longer suppress anything are errors.
-
-## Adjust the formatter
-
-The formatter uses 100 columns, two spaces, double quotes, semicolons and trailing commas. It sorts imports into value and type groups and sorts `package.json` scripts. To use single quotes or add a workspace import prefix:
-
 ```ts
 import { formatConfig } from "@jameswyse/oxc-config/oxfmt";
 
-export default {
-  ...formatConfig,
-  singleQuote: true,
-  sortImports: {
-    ...formatConfig.sortImports,
-    internalPattern: ["@/", "#", "@my-workspace/"],
-  },
-};
-```
-
-Tailwind class sorting depends on the project's Tailwind version and stylesheet, so configure Oxfmt's `sortTailwindcss` option in the project.
-
-## Develop
-
-```sh
-pnpm install --frozen-lockfile
-pnpm check
+export default formatConfig;
 ```
 
-`pnpm check` runs the rule tests, lints real consumer configs in temporary projects, checks type-aware diagnostics and formatter convergence, then lints, typechecks, checks formatting and builds `dist`.
-
-## Release
+Type-aware checking is on by default and needs a `tsconfig.json` that TypeScript 7 accepts. The defaults enable no framework profiles or project boundaries. The [configuration guide](docs/configuration.md) covers supported versions, scripts, framework profiles, project boundaries, the shared tsconfig, exceptions and formatter options.
 
-Add a changeset to any pull request that should ship:
-
-```sh
-pnpm changeset
-```
+## Documentation
 
-On `main`, the release workflow keeps a "chore(release): version packages" pull request up to date with the pending changesets. Merging it publishes the new version to npm with provenance, tags it and creates a GitHub release.
+- [Configuration guide](docs/configuration.md)
+- [Agent setup instructions](docs/agent-setup.md)
+- [Rule reference](REFERENCE.md)
+- [Contributing](CONTRIBUTING.md)
 
 ## Vendored code
 

package/REFERENCE.md

@@ -1,134 +1,107 @@
 # Rule reference
 
-## Defaults
-
-The base config enables Oxlint's correctness and suspicious categories as errors. It also enables strict equality, mandatory braces, `prefer-const`, no parameter reassignment, unused-variable checks that ignore `_`-prefixed bindings, import ordering and duplicate checks, the accumulating-spread check, named exports and no console logging. Unused suppression comments are errors. `no-underscore-dangle` is off so schema-owned fields such as `_id` and `__typename` remain valid.
-
-Warnings do not fail the run. The warning-level rules mark patterns that are usually worth changing but have legitimate uses that no syntax separates; each was measured on real codebases before it was added.
-
-## Standards and rules
-
-| Standard                                              | Implemented automation                                                                                                                                             | Limit                                                                                                                                                           |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| No `any`; keep unknown external values at a seam      | `typescript/no-explicit-any`; type-aware `no-unsafe-*`; `no-unsafe-dictionary-type`, `no-known-value-widening`, `no-unknown-returns` and `no-unknown-type-aliases` | Legitimate parsers may need narrow exceptions; imported domain types require type-aware analysis                                                                |
-| Parse external data at a seam instead of probing it   | `wyse/no-runtime-typeof` warns about `typeof` outside type guards; `typeof x === "undefined"` probes are allowed                                                   | Narrowing a known primitive union with `typeof` is legitimate; the warning prompts a schema without blocking                                                    |
-| Prefer validated narrowing and `satisfies`            | Native `no-non-null-assertion`; type-aware `no-unsafe-type-assertion`, `no-unnecessary-type-assertion`; `no-chained-type-assertions` and `no-widen-then-assert`    | No syntactic rule proves a runtime schema or invariant correct                                                                                                  |
-| Guards have truthful, recognisable names              | Custom `wyse/type-guard-name`                                                                                                                                      | Names do not prove predicate correctness                                                                                                                        |
-| Handle every union case                               | Type-aware `typescript/switch-exhaustiveness-check`                                                                                                                | The compiler still owns `never` assignments and valid-state modelling                                                                                           |
-| Remove redundant guards and dead code                 | Correctness/suspicious categories; unused variables/private members; type-aware `no-unnecessary-condition`                                                         | Whether validation belongs at another seam needs review                                                                                                         |
-| Keep branches readable                                | Custom `wyse/no-deep-ternary`; native `curly`                                                                                                                      | Complexity, line count and parameter count are not used as design proxies                                                                                       |
-| Handle asynchronous work and errors                   | Native correctness/promise checks, `no-empty`, `no-useless-catch`; typed floating/misused promises, `await-thenable`, `return-await`, `only-throw-error`           | Meaningful recovery, domain results, retry policy and error context need review                                                                                 |
-| Represent expected failures instead of silencing them | Custom `wyse/no-swallowed-errors` (warning)                                                                                                                        | Parser, filesystem-probe and existing-promise catches are allowed; other expected failures need a suppression with a reason                                     |
-| Avoid boolean control parameters                      | Custom `wyse/explicit-api-states` (warning)                                                                                                                        | Final boolean parameters of `set*`/`update*` functions are allowed; a boolean that is domain data still warns                                                   |
-| Named exports and imports from an owner               | `import/no-default-export`, `first`, `no-duplicates`, `no-self-import`, `no-unassigned-import`; warnings from `import/no-cycle` and `oxc/no-barrel-file`           | Internal barrel ownership and public package entrypoints need architectural context; the barrel rule counts only `export *` fan-out above its default threshold |
-| Name files after their concept                        | Custom `wyse/no-generic-file-suffix`                                                                                                                               | Files named after a domain export, such as `agentPolicy.ts` exporting `AgentPolicy`, and standard header policies are allowed                                   |
-| Import from the authoritative module                  | Custom `wyse/no-forwarding-module` (warning)                                                                                                                       | Package entrypoints and framework route files are allowed; other frameworks' mandated re-export files may need an exception                                     |
-| Remove middle men                                     | Custom `wyse/no-pass-through-function` (warning)                                                                                                                   | Only identifier callees are checked, because method facades usually hide an instance                                                                            |
-| No shipped console logging                            | `eslint/no-console`; narrow config/script exceptions                                                                                                               | Redaction, sensitive fields and sufficient structured context need review                                                                                       |
-| Never add code comments                               | Custom `wyse/no-comments`; tool directives and JavaScript type JSDoc remain allowed                                                                                | Projects can allow further directive patterns; the rule cannot tell whether the removed intent reached a name, type, test or commit                             |
-| Parse configuration at startup                        | Custom `wyse/no-env-access` with the project's `env` owners                                                                                                        | Owners must be named by the project; the rule does not check that the owner validates what it reads                                                             |
-| Keep privileged modules out of other runtimes         | Custom `wyse/import-boundaries` from the project's `boundaries`                                                                                                    | Only static, dynamic-literal and re-export specifiers are checked; `require` and computed imports are not                                                       |
-| Enforce authorisation at the protected operation      | Custom `wyse/server-action-guard` with the project's `serverActionGuards`                                                                                          | A guard's name cannot prove it authorises the operation or checks the right resource                                                                            |
-| Control time and randomness                           | Custom `wyse/no-ambient-clock` and `wyse/no-ambient-random` with the project's `clock` and `random` owners                                                         | Production code only; owners must be named by the project                                                                                                       |
-| Harden Electron apps                                  | Custom `wyse/electron-*` rules and a renderer import boundary in the `electron` profile                                                                            | Checks literal `webPreferences`, `remote` usage and raw `ipcRenderer` exposure through `contextBridge`                                                          |
-| Prefer local state and avoid accidental mutation      | `prefer-const`, `no-param-reassign`; React immutability checks; typed `prefer-readonly`                                                                            | Local accumulator mutation is allowed; ownership is not inferred from a variable name                                                                           |
-| Avoid repeated growing copies                         | Native `oxc/no-accumulating-spread`; `no-array-filter-map` and `no-reduce-accumulator-copy`; optional e18e profile                                                 | No performance improvement is claimed without measurement                                                                                                       |
-| Avoid duplicate React state and effect chains         | React and React Compiler native rules; `react-you-might-not-need-an-effect` rules                                                                                  | Product interactions still need runtime verification                                                                                                            |
-| Basic accessible JSX                                  | Native `jsx-a11y` correctness/suspicious rules in the React profile                                                                                                | Keyboard behaviour, accessible names through custom components and visual contrast require application evidence                                                 |
-| Tests execute assertions and are not silently skipped | Native Jest/Vitest focused/disabled/conditional/standalone/valid expectation checks                                                                                | Valid helper-based assertions are allowed; assertion-count rules are not enabled blindly                                                                        |
-| Tests wait for observable outcomes                    | Custom `wyse/no-fixed-test-delay`                                                                                                                                  | Genuine timer tests need a scoped exception; unknown wait helpers are not guessed                                                                               |
-| Tests have a non-vacuous oracle                       | Custom `wyse/no-vacuous-test-assertions`                                                                                                                           | Independent expected results and meaningful behavioural coverage still need review                                                                              |
-| Tests protect behaviour, not edits                    | Custom `wyse/no-edit-proof-assertions`                                                                                                                             | Only existence checks of imports and `typeof … "function"` checks are recognised                                                                                |
-| Tests do not hide slow or flaky work                  | Custom `wyse/no-test-timeout-overrides` (warning, unit tests only)                                                                                                 | End-to-end suites legitimately need longer timeouts and are excluded                                                                                            |
-| Tests sit beside the module they cover                | Custom `wyse/companion-has-owner` (warning)                                                                                                                        | Cross-module tests should be named `<behaviour>.integration.test` or live under `tests/`                                                                        |
-| Avoid module mocking of runnable dependencies         | `wyse/no-module-mocking`                                                                                                                                           | External systems can justify a file-scoped exception                                                                                                            |
-| Consistent layout and imports                         | Oxfmt; custom `wyse/statement-spacing`                                                                                                                             | Blank lines are only required around imports, multiline blocks, multiline declarations and returns, so deliberate groups of one-line statements stay together   |
-
-`no-unnecessary-condition` is a nursery rule in Oxlint 1.86.0. It is enabled only with `typeAware`. The usual native nested-ternary rule conflicts with Oxfmt 0.71.0 because one tool adds parentheses and the other removes them. The custom depth rule allows one nested level and reports the third ternary level, without prescribing parentheses.
-
-## Custom rules
-
-All rules use Oxlint's supported AST and lexical scopes and their tests sit beside their source, in `src/rules` or, for rules adapted from anti-slop, `src/vendor/anti-slop`. Only `statement-spacing` has an autofix, which inserts blank lines; its engine is adapted from ESLint Stylistic's `padding-line-between-statements`. `companion-has-owner` and `no-forwarding-module` read sibling files and the nearest `package.json`. The others are dependency-free.
-
-| Rule                                    | Rejected pattern                                                                                                                                                                                                                                 | Allowed or outside scope                                                                                                                                                                                                                                                                  |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type-guard-name`                       | A named predicate such as `checkUser(value): value is User`                                                                                                                                                                                      | `isUser`, `hasId`, assertion functions, anonymous callbacks and computed method names                                                                                                                                                                                                     |
-| `no-deep-ternary`                       | A conditional expression nested inside two conditional expressions                                                                                                                                                                               | One nested level; a separate function's expressions start a new depth                                                                                                                                                                                                                     |
-| `no-fixed-test-delay`                   | Awaited literal timer delays and known Playwright fixture `waitForTimeout` calls in recognised tests                                                                                                                                             | Local functions that shadow timer/test names, nonliteral delays, and unknown custom helpers                                                                                                                                                                                               |
-| `no-vacuous-test-assertions`            | Literal-to-literal equality expectations or the same identifier on both sides of `toBe`, `toEqual`, `toStrictEqual`                                                                                                                              | Computed values, property getters, reversed meaningful expectations and promise resolution matchers                                                                                                                                                                                       |
-| `no-comments`                           | Line, block and JSDoc comments, including JSDoc in TypeScript files                                                                                                                                                                              | Shebangs, JSDoc with type tags in JavaScript files, and tool directives: lint suppressions, `@ts-expect-error`, triple-slash references, `#__PURE__`, formatter and coverage ignores, bundler magic comments, test-environment and JSX pragmas; extra patterns through the `allow` option |
-| `no-env-access`                         | `process.env`, `import.meta.env` and destructuring `env` from either, outside `env` owners, config files and scripts                                                                                                                             | Local bindings named `process` and unrelated `env` properties                                                                                                                                                                                                                             |
-| `import-boundaries`                     | A value import, re-export or literal dynamic import from a configured scope whose specifier or resolved relative path matches a `deny` glob                                                                                                      | Type-only imports and files outside the boundary's scope                                                                                                                                                                                                                                  |
-| `server-action-guard`                   | An exported action in a `"use server"` module, or an inline `"use server"` function, whose first statement does not await a configured guard; indirect or default exports from server-action modules                                             | Non-exported helpers in server-action modules and test files                                                                                                                                                                                                                              |
-| `statement-spacing`                     | A missing blank line after the imports, around a multiline block or a multiline declaration, including exported ones, or before `return`                                                                                                         | Consecutive imports, consecutive one-line statements, and a type alias directly after the multiline declaration it derives from                                                                                                                                                           |
-| `no-edit-proof-assertions`              | `toBeDefined`, `toBeTruthy` and similar on an imported binding or namespace member; `typeof X` or `toBeTypeOf` against a string on imports; `toBeTypeOf("function")` on anything; `toHaveProperty` on a namespace                                | Assertions on values produced by running code                                                                                                                                                                                                                                             |
-| `no-test-timeout-overrides`             | Per-test or per-suite timeout and retry options, `test.setTimeout`, `test.slow()`, `describe.configure`, `vi.setConfig` and `jest.setTimeout` in unit tests                                                                                      | End-to-end files under `e2e/` or named `*.e2e.*`                                                                                                                                                                                                                                          |
-| `companion-has-owner`                   | A `.test`, `.spec` or `.bench` file whose name prefix matches no sibling module or directory, nor its own directory                                                                                                                              | Files with an `integration` or `e2e` segment and files under `tests/`, `test/`, `__tests__/` or `e2e/`                                                                                                                                                                                    |
-| `no-generic-file-suffix`                | A file named `*Contract`, `*Policy`, `policy` or `contract` in camel, kebab, snake or dot form                                                                                                                                                   | Test and story files, standard header policies such as content security policy, and files exporting a binding with the file's name                                                                                                                                                        |
-| `no-forwarding-module`                  | A module made only of re-exports, or imports re-exported unchanged                                                                                                                                                                               | Package entrypoints in the nearest `package.json`, Next.js `app` special files and `pages`, root `middleware`/`proxy`/`instrumentation`, modules with directives or side-effect imports                                                                                                   |
-| `no-pass-through-function`              | A named function whose body only calls an identifier with exactly its own parameters, in order                                                                                                                                                   | Zero-parameter functions, method callees, type predicates and `useEffectEvent` callees                                                                                                                                                                                                    |
-| `explicit-api-states`                   | A `boolean`, optional `boolean`, or boolean-defaulted parameter on an exported function, exported class constructor or public method                                                                                                             | Destructured parameters, accessors, private members, overloads and the final boolean of a `set*`/`update*` function                                                                                                                                                                       |
-| `no-swallowed-errors`                   | A `catch` whose body only returns a fallback literal, and a `.catch` callback that is empty or returns one                                                                                                                                       | Built-in parser and filesystem-probe try blocks, `response.json()`, and `.catch` on a promise another caller also receives                                                                                                                                                                |
-| `no-ambient-clock`                      | `Date.now()` and argument-less `new Date()`, including through `globalThis`/`window`                                                                                                                                                             | Parameter defaults, uncalled `Date.now` and provider functions that only return the read                                                                                                                                                                                                  |
-| `no-ambient-random`                     | `Math.random()`, `crypto.randomUUID()`, and `randomUUID`/`randomInt` from `node:crypto`                                                                                                                                                          | The same injection seams; `randomBytes` and `getRandomValues`, which generate secrets                                                                                                                                                                                                     |
-| `electron-no-remote-module`             | `remote` from `electron`, and `@electron/remote` by import, `require`, dynamic import or re-export                                                                                                                                               | Other Electron APIs                                                                                                                                                                                                                                                                       |
-| `electron-secure-web-preferences`       | `webPreferences` without literal `contextIsolation: true`, `sandbox: true` and `nodeIntegration: false`, or with insecure web security, insecure content, experimental or Blink features; overrides through later keys, spreads or computed keys | Preferences passed from a variable the rule cannot resolve                                                                                                                                                                                                                                |
-| `electron-no-raw-ipc-renderer-exposure` | Exposing `ipcRenderer` or its methods through `contextBridge`, forwarding renderer-chosen channels or arguments, or passing renderer callbacks straight to `on`/`once`                                                                           | Narrow, named preload functions with fixed channels                                                                                                                                                                                                                                       |
-
-Test-specific custom rules run on the default test globs, `tests` paths and any explicit Jest or Vitest profile scopes. Their import and binding recognition is deliberately narrower than unrestricted text matching. The tests are the executable reference for supported aliases, shadowing and callback forms.
-
-## Type, data and test-double rules
-
-The base config also enables these rules as errors:
-
-```text
-no-array-filter-map
-no-reduce-accumulator-copy
-no-chained-type-assertions
-no-conditional-empty-object-spread
-no-known-value-widening
-no-module-mocking
-no-object-parameters
-no-reflect-apply
-no-reflect-get
-no-shape-in-symbol-names
-no-unknown-returns
-no-unknown-type-aliases
-no-unsafe-dictionary-type
-no-widen-then-assert
-```
-
-`no-runtime-typeof` is a warning with `allowInTypeGuards` enabled. Banning `typeof` outright blocks legitimate narrowing of known unions, while the warning still points towards parsing external data with a schema. Projects can turn it off at a validated input seam.
-
-The optional `effect` profile enables `no-manual-effect-error-tag` and `no-service-constructor-imports`.
-
-These rules do not have cross-file type knowledge. Their [source files](src/vendor/anti-slop/rules) and tests define the supported same-file alias, scope and inference cases. There is no blanket ban on legitimate `unknown` values or invariant-preserving `as const` expressions.
-
-## Project-specific automation
-
-These policies are enforced once a project names the actual owners. They are intentionally not universal defaults:
-
-| Policy                                        | Mechanism                                                        | Required project information                                                      |
-| --------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Parse configuration at startup                | `env` option                                                     | Modules that own configuration parsing                                            |
-| Keep privileged modules out of other runtimes | `boundaries` option                                              | Each runtime's file scope, and the packages, aliases and paths it must not import |
-| Require access checks before server actions   | `serverActionGuards` option                                      | The guard functions that perform authorisation                                    |
-| Control time and randomness                   | `clock` and `random` options                                     | Modules that own the clock and ID or random generation                            |
-| Harden Electron apps                          | `electron` option                                                | Renderer globs when they are not `src/renderer/**`                                |
-| Generated assets and style imports            | Shared ignores plus local patterns; Oxfmt Tailwind configuration | Actual generators, CSS preprocessors, Tailwind config or stylesheet               |
-
-## Compiler settings and review work
-
-For new TypeScript projects, use `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride` and `noFallthroughCasesInSwitch`. The package exports them as `@jameswyse/oxc-config/tsconfig` for a project's `tsconfig.json` to extend. Lint configuration never applies them, because changing them in an existing project is a deliberate migration.
-
-Lint cannot establish correct authorisation, tenant isolation, schema validation, secret redaction, transaction boundaries, idempotency, crash recovery, concurrency ownership, dependency justification, useful module depth, constructive domain modelling or independent test oracles. These remain review and verification work. File naming, positional parameters, boolean inputs, `Partial<T>`, wrappers and abstraction counts have legitimate domain/framework exceptions and are not rejected through universal heuristics.
-
-## Oxc API references
-
-The implementation follows the current [Oxlint configuration API](https://oxc.rs/docs/guide/usage/linter/config.html), [JS plugin API](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html), [type-aware setup](https://oxc.rs/docs/guide/usage/linter/type-aware.html), and [Oxfmt options](https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html). Absolute plugin specifiers keep imported configs independent of the consumer's working directory. Side-effect import sorting is explicitly disabled.
-
-## Rules considered and dropped
-
-`no-call-count-assertions` would have rejected `toHaveBeenCalledTimes`, `toHaveBeenNthCalledWith` and `mock.calls` counting. On three codebases, 36 of 40 sampled findings were legitimate: the count was the behaviour under test, such as caching, retry, deduplication or firing once. No syntax separated them from incidental counts, so it was dropped.
-
-Rules for safety comments on type assertions, a blank line between every top-level statement, and rejecting `unknown` parameters are not included. The first conflicts with `no-comments`, the second split deliberate groups of related declarations, and the third rejected legitimate unparsed input seams. Effect rules that reject `_tag` comparisons, prefer `Match` or reject literal tagged construction are not included either, because discriminant checks are the preferred way to narrow a union and TypeScript already checks literal variants.
+Rules are errors, which fail the run, unless marked as warnings. Warnings flag patterns that have legitimate uses, so they report without failing. Custom rules use the `wyse/` prefix. Each one's tests sit beside it in `src/rules` or `src/vendor/anti-slop/rules` and show exactly what it reports.
+
+Framework profiles and project options add rules only when enabled. The [configuration guide](docs/configuration.md) explains how to turn them on.
+
+## Base rules
+
+Oxlint's correctness and suspicious categories are errors. Unused variables are errors unless their names start with `_`, and suppression comments that no longer suppress anything are errors too. `no-underscore-dangle` is off, so fields such as `_id` and `__typename` stay valid.
+
+Native rules also catch legacy and error-prone built-ins: `no-var`, `no-proto`, `no-new-func`, `no-new-wrappers`, `no-array-constructor`, `no-prototype-builtins`, `prefer-object-has-own`, `prefer-rest-params`, `prefer-regex-literals`, `import/no-mutable-exports`, `oxc/no-const-enum`, and Unicorn's `new-for-builtins`, `no-instanceof-array`, `no-new-buffer`, `prefer-node-protocol`, `prefer-import-meta-properties`, `prefer-response-static-json`, `prefer-string-trim-start-end`, `prefer-array-find`, `prefer-array-flat-map` and `prefer-array-some`.
+
+## Types and external data
+
+Native rules: `typescript/no-explicit-any`, `no-non-null-assertion`, `no-unsafe-function-type` and `no-import-type-side-effects`. `consistent-type-assertions` allows only `as` assertions and rejects them on object and array literals, and `method-signature-style` requires property signatures such as `run: () => void`. `ban-ts-comment` rejects `@ts-ignore` and `@ts-nocheck`, and requires a reason after `--` on `@ts-expect-error`.
+
+Type-aware checking, which is on by default, adds the `no-unsafe-*` rules, `no-unsafe-type-assertion`, `no-unnecessary-type-assertion`, `switch-exhaustiveness-check`, `prefer-reduce-type-parameter`, `restrict-plus-operands` with every mixed-type allowance turned off, and `no-unnecessary-condition`, a nursery rule in Oxlint 1.86. `typescript/no-deprecated` is a warning outside tests.
+
+- `wyse/no-runtime-typeof` (warning): `typeof` outside a type guard. `typeof x === "undefined"` passes, as does `typeof` on a variable or parameter declared in the same file with a union type that has no `unknown` or `any` member. Turn it off in modules that validate external input.
+- `wyse/no-generic-object-guard`: a named helper such as `isRecord` whose whole body proves only that a value is a non-null object, through `typeof`, `instanceof Object`, prototype or `Object.prototype.toString` checks. Guards that also check a field pass, as do inline callbacks. It also reports any guard that takes `unknown` or `any` and claims a specific type while only checking that the value exists, or always returns `true`.
+- `wyse/no-hardcoded-credential`: a string containing a private key or a token in a well-known format, such as an AWS access key or a GitHub, Stripe live, Slack, Google, Anthropic or OpenAI key. Placeholders containing `example`, `fake`, `dummy`, `placeholder`, `redacted` or a run such as `abcdefgh` pass.
+- `wyse/no-disabled-tls-verification`: `rejectUnauthorized: false`, or setting `NODE_TLS_REJECT_UNAUTHORIZED` to `"0"`.
+- `wyse/no-secret-fallback`: a string fallback for an environment variable whose name contains `SECRET`, `TOKEN`, `PASSWORD`, `PRIVATE`, `CREDENTIAL`, `SALT`, `SIGNING` or `API_KEY`, or ends in `KEY`, such as `process.env.SESSION_SECRET ?? "dev"` or a destructuring default.
+- `wyse/type-guard-name`: a named type predicate such as `checkUser(value): value is User`. Names such as `isUser` and `hasId` pass, as do assertion functions and anonymous callbacks.
+- `wyse/no-unknown-returns`: a declared return type of `unknown` or `Promise<unknown>`.
+- `wyse/no-unknown-type-aliases`: a type alias that resolves to `unknown`.
+- `wyse/no-unsafe-dictionary-type`: a dictionary type whose values are `unknown`, `any`, `object` or `{}`.
+- `wyse/no-object-parameters`: a parameter typed `object`, directly or through an alias.
+- `wyse/no-known-value-widening`: a known value stored under a broader declared type, such as `const value: unknown = {}`.
+- `wyse/no-widen-then-assert`: widening a known value, then asserting it to a narrower type.
+- `wyse/no-chained-type-assertions`: chained assertions such as `value as unknown as User`.
+- `wyse/no-reflect-apply` and `wyse/no-reflect-get`: `Reflect.apply` and `Reflect.get`.
+
+These custom rules check one file at a time, without type information from other files. None of them bans `unknown` outright or rejects `as const`.
+
+## Control flow and errors
+
+Native rules: `curly`, `eqeqeq`, `no-empty`, `no-useless-catch`, Oxlint's promise checks, `array-callback-return`, `no-case-declarations`, `no-constructor-return`, `no-fallthrough`, `no-loop-func`, `no-self-compare`, `no-unreachable-loop`, `no-useless-assignment` and `unicorn/error-message`. JavaScript files also get `no-throw-literal` and `prefer-promise-reject-errors`. Type-aware checking adds floating and misused promise checks, `await-thenable`, `return-await`, `only-throw-error`, `prefer-promise-reject-errors` and `use-unknown-in-catch-callback-variable`.
+
+- `wyse/no-deep-ternary`: a ternary nested inside two others. It replaces Oxlint's nested-ternary rule, which conflicts with Oxfmt over parentheses.
+- `wyse/no-swallowed-errors` (warning): a `catch` that only returns a fallback literal, a `.catch` callback or `.then` rejection callback that is empty or only returns one, and `Promise.allSettled` results that are never read. Effect's `orElseSucceed`, `orElse`, `catchAll` and `catchAllCause` count when they recover to a fallback literal or `Effect.void`. Built-in parser and filesystem-probe `try` blocks, `response.json()`, `.catch` on a promise another caller also receives, and Effect's `catchTag` all pass.
+- `wyse/explicit-api-states` (warning): a boolean parameter on an exported function, exported class constructor or public method. Destructured parameters, accessors, private members, overloads, the subject of an `asserts` or `is` return type, and the final boolean of a `set*` or `update*` function pass.
+- `wyse/no-unsettled-promise`: a `new Promise` executor that runs code but never calls `resolve` or `reject`, or calls them only inside an optional call such as `server?.close(resolve)`. Executors that do nothing, such as `() => {}`, pass. Test files aren't checked.
+- `wyse/no-unchecked-index-search`: an `indexOf`, `lastIndexOf`, `findIndex` or `findLastIndex` result passed straight to `splice`, `toSpliced`, `with`, `at` or `slice`, where -1 counts from the end.
+- `wyse/no-unchecked-fetch-response`: reading a `fetch` response body with `json()`, `text()` or a similar method without checking `ok` or `status`. A response passed to another function passes. Test files aren't checked.
+
+## Modules, files and names
+
+Native rules: `import/first`, `import/no-default-export`, `import/no-duplicates`, `import/no-self-import` and `import/no-unassigned-import`. `import/no-cycle` and `oxc/no-barrel-file` are warnings. Default exports are allowed in the files that tools load them from, listed in the [configuration guide](docs/configuration.md#select-framework-and-runtime-profiles).
+
+- `wyse/no-forwarding-module` (warning): a module made only of re-exports, or one that re-exports its imports unchanged. Package entrypoints, Next.js `app` special files and `pages`, root `middleware`, `proxy` and `instrumentation` files, and modules with directives or side-effect imports pass.
+- `wyse/no-import-time-effects` (warning): starting a timer, `fetch`, top-level `await`, opening a `BroadcastChannel`, `WebSocket`, `EventSource` or `Worker`, calling `addEventListener` or `listen`, or registering `process.on` handlers when a module is imported, including inside immediately invoked functions and static class members. Config files, scripts, tests, and entrypoints such as `main`, `server`, `worker` and `instrumentation` files and `bin`, `cli`, `deploy`, `tools`, `test`, `e2e` and `fixtures` directories pass.
+- `wyse/no-pass-through-function` (warning): a named function whose body only calls another function with its own parameters, in order. Zero-parameter functions, method calls, type predicates and `useEffectEvent` callees pass.
+- `wyse/no-generic-file-suffix`: a file named `*Contract`, `*Policy`, `policy` or `contract`, in any case style. Test and story files pass, as do header policies such as a content security policy and files that export a binding with the file's name, such as `agentPolicy.ts` exporting `AgentPolicy`.
+- `wyse/no-shape-in-symbol-names`: a name containing "shape", in any letter case.
+
+## Comments, suppressions and logging
+
+- `wyse/no-comments`: line, block and JSDoc comments. Shebangs, JSDoc type tags in JavaScript files and tool directives pass. The directives include lint suppressions, `@ts-expect-error`, triple-slash references, `#__PURE__`, formatter and coverage ignores, bundler magic comments, and test-environment and JSX pragmas. The `allow` option adds more patterns.
+- `wyse/require-suppression-reason`: an `oxlint-disable` or `eslint-disable` directive that names no rule, or gives no reason after `--`. Oxlint applies a blanket `oxlint-disable` or `oxlint-disable-line` to this rule too, so it can't report those two forms. It does report a blanket `oxlint-disable-next-line`.
+- `eslint/no-console`: console calls outside config files and scripts.
+
+## Mutation and copying
+
+Native rules: `prefer-const`, `no-param-reassign` and `oxc/no-accumulating-spread`. Type-aware checking adds `prefer-readonly`.
+
+- `wyse/no-array-filter-map`: adjacent `filter` and `map` passes over an array.
+- `wyse/no-reduce-accumulator-copy`: copying a reducer's accumulator with `Object.assign`, `Array.from` or an array copy method.
+- `wyse/no-conditional-empty-object-spread`: spreading a conditional empty object to omit fields, such as `...(id ? { id } : {})`.
+
+## Project ownership
+
+These rules run only once the project names its owners through the [project boundary options](docs/configuration.md#enforce-project-boundaries).
+
+- `wyse/no-env-access` (`env`): reading `process.env` or `import.meta.env`, or destructuring `env` from either, outside the owners, config files and scripts. It doesn't check that the owner validates what it reads.
+- `wyse/import-boundaries` (`boundaries`): a value import, re-export, literal dynamic import, or `require` call, including a loader made with `createRequire` from `node:module`, that matches a `deny` glob. Type-only imports and `import("…")` types pass unless the boundary sets `types: true`. It doesn't check computed imports.
+- `wyse/server-action-guard` (`serverActionGuards`): a `"use server"` action that doesn't start by awaiting a guard, and indirect or default exports from server-action modules. Non-exported helpers and test files pass.
+- `wyse/no-ambient-clock` (`clock`): `Date.now()` and argument-less `new Date()`, including through `globalThis` or `window`. Parameter defaults, uncalled `Date.now`, provider functions that only return the read, and test files pass.
+- `wyse/no-ambient-random` (`random`): `Math.random()`, `crypto.randomUUID()`, and `randomUUID` or `randomInt` from `node:crypto`. The same exceptions apply. `randomBytes` and `getRandomValues` pass because they generate secrets.
+
+## Tests
+
+These rules run on the default test globs, the `tests` paths and the Jest and Vitest profile scopes. The `vitest` and `jest` profiles add native checks for focused, disabled and conditional tests, standalone expectations, valid `expect` calls, interpolated snapshots and redundant async `expect` callbacks. They also require the specific matcher, such as `toStrictEqual` over `toEqual`, `toHaveLength`, `toContain`, and comparison or equality matchers over `toBe(true)`. The `jest` profile rejects `done` callbacks.
+
+- `wyse/no-fixed-test-delay`: an awaited literal timer delay, Playwright's `waitForTimeout`, or `yield* Effect.sleep` with a fixed duration. Genuine timer tests need a scoped exception.
+- `wyse/no-vacuous-test-assertions`: an expectation that compares two literals, or the same identifier on both sides of `toBe`, `toEqual` or `toStrictEqual`.
+- `wyse/no-edit-proof-assertions`: an assertion that only proves an import exists or is a function, such as `toBeDefined` on an import, `toBeTypeOf("function")` or `toHaveProperty` on a namespace.
+- `wyse/no-optional-test-action`: a statement directly in a test body that an optional call can skip, such as `button?.click()` or `await dismiss?.click()`. Hooks and callbacks inside the test pass.
+- `wyse/no-derived-test-expectation` (warning): an expected value that calls a function imported from production code, such as `toBe(formatLabel(input))`, directly, through a namespace import or through a `const` such as `expected`. `.not` assertions, functions the actual value also calls, and imports from test, fixture, e2e and helper paths pass.
+- `wyse/no-uncontrolled-test-clock`: `Date.now()` or argument-less `new Date()` in a test file that never calls `useFakeTimers`, `setSystemTime`, `mock.timers.enable`, `clock.install` or `clock.setFixedTime`. Fake timers set up with `apis`, `toFake` or `doNotFake` options that leave `Date` real don't count, and neither does Effect's `TestClock`, which doesn't control `Date`. Playwright and end-to-end files pass.
+- `wyse/no-test-timeout-overrides` (warning): timeout and retry overrides such as `test.setTimeout`, `test.slow()`, `describe.configure`, `vi.setConfig`, `jest.setTimeout` and `jest.retryTimes`. Setting retries to 0 passes. End-to-end files under `e2e/` or named `*.e2e.*` pass.
+- `wyse/companion-has-owner` (warning): a `.test`, `.spec` or `.bench` file with no matching sibling module or directory. Files with an `integration` or `e2e` segment, and files under `tests/`, `test/`, `__tests__/` or `e2e/`, pass.
+- `wyse/no-module-mocking`: Vitest, Jest and `node:test` module mocking. Replace dependencies through real interfaces, or add a file-scoped exception for an external system.
+
+## Framework profiles
+
+- `react` adds React and React Compiler rules, `jsx-a11y` correctness and suspicious rules, `react-you-might-not-need-an-effect`, and e18e performance rules outside tests. It includes `react/rules-of-hooks` outside end-to-end and `tests` paths, `no-unknown-property`, `checked-requires-onchange-or-readonly` and `jsx-no-useless-fragment`. It also adds `wyse/no-get-password-form`: a `<form>` with a password or one-time-code input that can submit by GET. An input belongs to the form it sits inside, or to the form its `form` attribute names. The form submits by GET when its `action` is missing or a string and its `method` is missing or anything but `post` or `dialog`, or when one of its submit buttons sets `formMethod` to anything but `post` or `dialog`.
+- `nextjs` adds the React rules plus Next.js rules.
+- `effect` adds `wyse/no-manual-effect-error-tag` and `wyse/no-service-constructor-imports`. The second reports a project-local `make*` import used as an uncalled value, such as `yield* makeIssueService`. Calling a `make*` factory with arguments passes.
+- `electron` adds a renderer import boundary and these rules:
+  - `wyse/electron-no-remote-module`: `remote` from `electron`, or `@electron/remote`, by import, `require`, dynamic import or re-export.
+  - `wyse/electron-secure-web-preferences`: `webPreferences` without literal `contextIsolation: true`, `sandbox: true` and `nodeIntegration: false`, or with web security disabled, insecure content, or experimental or Blink features enabled. Later keys, spreads and computed keys that override these settings are reported too. Preferences passed from a variable the rule can't resolve pass.
+  - `wyse/electron-no-raw-ipc-renderer-exposure`: exposing `ipcRenderer` or its methods through `contextBridge`, forwarding renderer-chosen channels or arguments, or passing renderer callbacks straight to `on` or `once`.
+
+## Formatting
+
+Oxfmt formats the code. `wyse/statement-spacing` requires a blank line after the imports, around multiline blocks and declarations, and before `return`. Consecutive imports, consecutive one-line statements, and a type alias directly after the multiline declaration it derives from stay together. It's the only custom rule with an autofix.

package/dist/format.d.ts

@@ -1,5 +1,7 @@
-import type { OxfmtConfig, SortImportsConfig } from "oxfmt";
-export declare const formatConfig: OxfmtConfig & {
+import type { OxfmtConfig } from "oxfmt";
+type SortImportsOptions = Exclude<OxfmtConfig["sortImports"], boolean | undefined>;
+export declare const formatConfig: Omit<OxfmtConfig, "ignorePatterns" | "sortImports"> & {
     ignorePatterns: string[];
-    sortImports: SortImportsConfig;
+    sortImports: SortImportsOptions;
 };
+export {};