@mkrz/oxlint-config 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0 (2026-09-04)
+
+First release.
+
+- `mkrz(options?, config?)` builds the whole ruleset as one flat root config
+  and layers your own root config on top.
+- `repositoryType: 'app' | 'library' | 'monorepo' | 'auto'` decides where the
+  disable-directive policy applies; `auto` reads the working directory.
+- `typeAware` warns and runs without type-checked rules when
+  `oxlint-tsgolint` is not installed; an explicit `true` throws.
+- `defineConfig` wrapper that folds `ignorePatterns`, `env`, `globals`, and
+  `settings` from extended configs into the root, since Oxlint drops them.
+- Custom rules at `@mkrz/oxlint-config/plugin`, including a port of
+  `padding-line-between-statements` so the package has no ESLint dependency.
+- Vendored anti-slop rules with local fixes; see
+  `src/plugin/rules/vendor/anti-slop/README.md`.
+
+- Config inheritance preserves nested root settings and consumer ignore patterns.
+- Hook rules resolve imports by binding, and type rules respect shadowed types.
+- Monorepo restrictions cover static CommonJS application imports as well as ESM.
+- Missing store selectors include explicit `undefined` and `void` arguments.
+- Type-aware availability follows the consumer executable search path.
+- Custom rule documentation, effective policy snapshots, and a repeatable consumer benchmark.
+- Release publishing uses the exact tested tarball; pack tests support quoted paths.
+- Padding autofixes preserve CRLF and keep directive comments attached to their code.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Kreuzmayr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.anti-slop

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dillon Mulroy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.stylistic

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright OpenJS Foundation and other contributors, <www.openjsf.org>
+Copyright (c) 2023-PRESENT ESLint Stylistic contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# @mkrz/oxlint-config
+
+`@mkrz/oxlint-config` is the Oxlint setup I use for TypeScript and React
+projects. It is a set of guard-rails, not a starting point: every rule runs at
+error severity, and the switches turn whole concerns off, never individual
+rules.
+
+## Read this first
+
+The ruleset rejects code that most projects accept. Expect the first run on an
+existing codebase to report a lot.
+
+- `let` is an error, including `for (let i = 0; …)`. Use `const` and derive a
+  new value; use `for…of`.
+- `../` imports are an error everywhere, inside packages too. Set up path
+  aliases or package imports first.
+- `as T` is an error except `as const`. Parse the value with a runtime schema
+  library or narrow it with a type guard.
+- `unknown` parameters and return types are errors.
+- With `react` on: `useEffect`, `useLayoutEffect`, `useInsertionEffect`,
+  `useMemo`, `useCallback`, `useReducer`, and `useSyncExternalStore` are
+  errors.
+- In test files, `vi.mock` and `jest.mock` are errors. The test override
+  relaxes assertions, not mocking.
+- Disable comments are policed: none at all in applications, one named
+  `oxlint-disable-next-line <rule> -- reason` in libraries and packages.
+- Test files are assumed to use vitest.
+- Blank lines between multi-line statements, blocks, and before `return` are
+  enforced. This is a style rule with an autofix (`oxlint --fix`), not a
+  correctness check; it does not conflict with oxfmt or Prettier.
+
+## Install
+
+```sh
+pnpm add -D oxlint @oxlint/plugins oxlint-tsgolint @mkrz/oxlint-config
+```
+
+`@oxlint/plugins` is a peer dependency so its version always matches the
+`oxlint` you run. `oxlint-tsgolint` powers the type-aware rules; without it
+the default config warns and runs without them.
+
+Oxlint cannot resolve npm package names from the `extends` array in
+`.oxlintrc.json`. Use an `oxlint.config.ts` file and import from this package
+instead. Node 22.18 or newer is required because Oxlint loads that file at
+runtime. The package has no ESLint dependency; every custom rule, including the
+blank-line rule, runs as an Oxlint JS plugin.
+
+## Use
+
+Add an `oxlint.config.ts` file at the root of your project:
+
+```ts
+import { mkrz } from '@mkrz/oxlint-config';
+
+export default mkrz();
+```
+
+`mkrz(options?, config?)` returns one flat Oxlint root config. The plugin is
+declared once, the `correctness` and `suspicious` categories are on at error
+severity once, and there is no subset that fails to load or runs at warning
+severity.
+
+### Options
+
+```ts
+export default mkrz({
+  react: false,
+  typeAware: true,
+  repositoryType: 'monorepo',
+  appsPath: ['products/**'],
+  packagesPath: ['modules/**'],
+  appPackages: ['@acme/shop', '@acme/admin-*'],
+});
+```
+
+- `react` (default `true`): accessibility, React Compiler, hooks, query, and
+  store rules. Turn off for Node services and libraries without JSX.
+- `typeAware` (default `true`): type-checked TypeScript rules. Needs a
+  tsconfig and `oxlint-tsgolint`, and costs more lint time. When
+  `oxlint-tsgolint` is not installed, the default prints a warning and runs
+  without these rules; an explicit `typeAware: true` throws.
+- `repositoryType` (default `'auto'`): where the disable-directive policy
+  applies. See below. `appsPath`, `packagesPath`, and `appPackages` are only
+  accepted together with `repositoryType: 'monorepo'`.
+
+### Your own settings
+
+Pass your root config as the second argument. Its `rules` replace this
+package's root rules, its `overrides` run after this package's, and its
+`ignorePatterns`, `env`,
+`globals`, `settings`, and `plugins` are merged with the ruleset's:
+
+```ts
+import { mkrz } from '@mkrz/oxlint-config';
+
+export default mkrz(
+  { react: false },
+  {
+    ignorePatterns: ['**/generated/**'],
+    rules: {
+      'mkrz/no-let': 'off',
+    },
+    overrides: [
+      {
+        files: ['scripts/**'],
+        rules: { 'no-alert': 'off' },
+      },
+    ],
+  }
+);
+```
+
+File overrides take precedence over root rules. To change a rule supplied by
+one of this package's overrides, add a matching override of your own. For
+example, to relax the application directive policy:
+
+```ts
+export default mkrz(
+  { repositoryType: 'app' },
+  {
+    overrides: [
+      { files: ['**/*'], rules: { 'mkrz/no-oxlint-disable': 'off' } },
+    ],
+  }
+);
+```
+
+If you compose with Oxlint's `extends` instead, use the `defineConfig` export
+of this package. Oxlint only honors `ignorePatterns`, `env`, `globals`, and
+`settings` on the root config and drops them from extended configs; the
+wrapper folds them back in. The ignore list is also exported as
+`ignorePatterns`.
+
+## Repository types
+
+- `app`: no Oxlint or ESLint disable comment anywhere.
+- `library`: a single named `oxlint-disable-next-line <rule> -- reason`
+  comment is allowed.
+- `monorepo`: the `app` policy under `appsPath` (default `apps/**`), the
+  `library` policy under `packagesPath` (default `packages/**`). Files outside
+  both, such as root configs, get neither. Packages may not import the
+  workspace package names listed in `appPackages` (gitignore-style globs).
+  Relative paths that climb out of a package are already rejected by
+  `import/no-relative-parent-imports`.
+- `auto` (the default) reads the directory Oxlint runs in: a
+  `pnpm-workspace.yaml` with `packages`, a `workspaces` field, or an `apps/`
+  or `packages/` directory means `monorepo`. Otherwise `"private": true` in
+  `package.json` means `app` and anything else `library`. Without a
+  `package.json` it falls back to `app` and says so. A workspace without
+  `apps/` or `packages/` is still `monorepo`, but the policy overrides would
+  then match nothing, so it warns and asks for explicit `appsPath` and
+  `packagesPath`. It is the working
+  directory, not the directory of `oxlint.config.ts`, because a config file
+  cannot learn its own location from Oxlint; run Oxlint from the repository
+  root or set the type explicitly.
+
+Unused disable directives are always reported. One bypass the directive rules
+cannot close themselves: a file-level
+`/* oxlint-disable mkrz/no-oxlint-disable */` comment suppresses the very rule
+that reports it and counts as a used directive. The bare `/* oxlint-disable */`
+form is still caught by `unicorn/no-abusive-eslint-disable`. Catching the
+named form needs an out-of-band check, such as a CI grep for
+`oxlint-disable mkrz/`.
+
+## React policy
+
+`react` rejects `useEffect`, `useLayoutEffect`, `useInsertionEffect`,
+`useReducer`, `useSyncExternalStore`, `useMemo`, and `useCallback`. There is
+deliberately no sanctioned way to subscribe to something outside React by
+hand; that is what the query and store libraries are for. Oxlint's native
+ports of the React Compiler and rules-of-hooks checks run as errors, so no
+ESLint plugin is loaded for React. The rule sees hooks imported from `react`
+and called as `React.useEffect`; a local re-export of React is not followed.
+
+With `react` on, both the `browser` and `node` environments are enabled for
+every file. Universal code (server components, loaders) needs both, and file
+location cannot tell them apart. Use separate tsconfigs with appropriate
+`lib` and `types` settings to check environment-specific globals.
+
+Side-effect imports are rejected by `import/no-unassigned-import`, except
+stylesheets (`.css`, `.scss`, `.sass`, `.less`). Add other side-effect modules
+such as `server-only` through your root config's `rules`.
+
+Query and store hooks are matched by name, on direct calls only: anything of
+the form `use*Query`, `use*Queries`, or `use*Mutation` counts as a query hook,
+and a bound zustand hook named after its store, `use<Name>Store`, counts as a
+store hook, so wrapper hooks such as `useUserQuery` follow the same policy.
+Aliases such as `const query = useQuery` are not followed. Query results
+cannot be object-destructured, and a cast or parentheses do not hide the call.
+Keeping the result together is a project convention: it makes the source of
+each field visible and keeps checks and reads on the same object. TypeScript
+can preserve narrowing for `const { data, isSuccess } = useQuery()` when both
+bindings come from the same destructuring declaration. This rule deliberately
+rejects that valid form too. For mutations, write
+`const mutation = useMutation(...)` and call `mutation.mutate`. Store
+hooks must receive a selector, and the selector may not return the whole
+state. The store rule is written for zustand: the
+bare `useStore(store, selector)` is checked when it is imported from `zustand`
+or `zustand/react`, and a `useStore` from any other module (react-redux,
+MobX) is left alone. Name bound stores by domain; a local
+`const useStore = create(...)` is not recognised. `useSyncExternalStore` is
+not treated as a store hook (it is rejected by the hook policy above
+instead).
+
+## Base policy
+
+`base` is always on. It turns the `correctness` and `suspicious` categories on
+at error severity for every enabled plugin and lists only the rules outside
+those categories. Three of the listed rules (`no-unreachable-loop`,
+`typescript/prefer-optional-chain`, `react/require-render-return`) are in
+Oxlint's nursery and may be renamed between Oxlint minors.
+
+Test files (`**/*.{test,spec}.*`, `**/*.test-d.*`, `**/__tests__/**`) get the
+vitest plugin and may use type assertions and non-null assertions.
+
+## Custom rules
+
+The custom rules ship from the same package at `@mkrz/oxlint-config/plugin`.
+`mkrz()` loads that subpath itself, so consumers do not configure it
+separately.
+
+Rules written for this package:
+
+- `mkrz/no-app-requires`: the CommonJS counterpart to monorepo import restrictions.
+- `mkrz/no-let`
+- `mkrz/no-oxlint-disable` and `mkrz/package-disable-policy`
+- `mkrz/no-query-result-destructuring`
+- `mkrz/no-restricted-react-hooks`
+- `mkrz/require-store-selector`
+- `mkrz/no-type-assertion`
+- `mkrz/padding-line-between-statements`: a port of the `@stylistic` rule of
+  the same name, with the same options and messages. Oxlint has no esquery,
+  so the `selector` option accepts `*` or an exact AST node type instead of a
+  full selector.
+
+Rules vendored from Dillon Mulroy's anti-slop project, enabled as errors by
+default. The assertion and widening checks are relaxed in test files:
+
+- `mkrz/no-chained-type-assertions`
+- `mkrz/no-known-value-widening`
+- `mkrz/no-module-mocking`
+- `mkrz/no-reflect-apply`
+- `mkrz/no-reflect-get`
+- `mkrz/no-unknown-parameters`
+- `mkrz/no-unknown-returns`
+- `mkrz/no-unknown-type-aliases`
+- `mkrz/no-unsafe-dictionary-type`
+- `mkrz/no-widen-then-assert`
+
+Examples and migration guidance for every custom rule are in
+[the rule reference](docs/rules.md). Each diagnostic links to its rule there.
+The CommonJS boundary rule uses `ignore` to match the same gitignore-style
+patterns as the native ESM restriction. Dynamic CommonJS module names cannot
+be checked statically; literal `require` and `module.require` calls are checked.
+
+The local changes made to the vendored rules are listed in
+`src/plugin/rules/vendor/anti-slop/README.md`.
+
+## Versions
+
+The peer ranges on `oxlint`, `@oxlint/plugins`, and `oxlint-tsgolint` use `~`
+because Oxlint's JS plugin API is not covered by semver yet; expect a release
+of this package per Oxlint minor. This has a consequence for npm users: npm
+treats an unmet peer range as an install error, so you cannot move to a new
+Oxlint minor until this package has followed (pnpm only warns). Renovate opens
+one grouped PR per Oxlint release, and the tarball is installed and linted in
+CI before every release.
+
+## Maintaining the policy
+
+`pnpm test` compares the effective native rules, severities, options, and
+custom overrides against `src/__snapshots__/policy.json`. After an intentional
+policy or Oxlint update, run `pnpm run test:update-policy` and review the diff.
+
+`pnpm run benchmark` measures cold-process linting of a generated TypeScript
+consumer with type awareness on and off. See [the benchmark notes](docs/performance.md)
+for the fixture, measured results, and limits.
+
+## License
+
+MIT. The vendored anti-slop code keeps Dillon Mulroy's MIT license and the
+blank-line rule keeps the ESLint Stylistic license. The package includes
+copies at `LICENSE.anti-slop` and `LICENSE.stylistic`.

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { OxlintConfig } from "oxlint";
+//#region src/configs/ignore-patterns.d.ts
+/**
+ * Build output, caches, and lockfiles that should never be linted.
+ *
+ * Oxlint only honors `ignorePatterns` on the root config; patterns inside an
+ * extended config are dropped. Spread this list into the root config.
+ */
+declare const ignorePatterns: string[];
+//#endregion
+//#region src/configs/monorepo.d.ts
+type MonorepoOptions = {
+  /** Globs for application source. Defaults to `['apps/**']`. */
+  appsPath?: string[];
+  /** Globs for shared package source. Defaults to `['packages/**']`. */
+  packagesPath?: string[];
+  /**
+   * Workspace package names of applications, as gitignore-style globs such as
+   * `['@acme/web', '@acme/admin-*']`. Packages may not import them.
+   */
+  appPackages?: string[];
+};
+//#endregion
+//#region src/configs/repository.d.ts
+/**
+ * What kind of repository the ruleset runs in. It decides where the
+ * disable-directive policies apply:
+ *
+ * - `app`: no disable comments anywhere.
+ * - `library`: a single named `oxlint-disable-next-line <rule> -- reason`
+ *   comment is allowed anywhere.
+ * - `monorepo`: the app policy under `appsPath`, the library policy under
+ *   `packagesPath`, and packages may not import applications.
+ */
+type RepositoryType = 'app' | 'library' | 'monorepo';
+//#endregion
+//#region src/mkrz.d.ts
+type Switches = {
+  /**
+   * React, accessibility, React Compiler, query, and store rules. Turn off
+   * for Node services and libraries without JSX. Defaults to `true`.
+   */
+  react?: boolean;
+  /**
+   * Type-checked rules. These need a tsconfig and `oxlint-tsgolint`, and cost
+   * more lint time. Defaults to `true`; when `oxlint-tsgolint` is not
+   * installed the default warns and runs without them, while an explicit
+   * `true` throws.
+   */
+  typeAware?: boolean;
+};
+type MkrzOptions = (Switches & {
+  /**
+   * Where the disable-directive policies apply. `auto` (the default) reads
+   * the working directory: a `pnpm-workspace.yaml` with `packages`, a
+   * `workspaces` field, or an `apps/` or `packages/` directory means
+   * `monorepo`; otherwise `"private": true` in `package.json` means `app`
+   * and anything else `library`. Without a `package.json` it falls back
+   * to `app` with a warning.
+   *
+   * The working directory is used because a config file cannot learn its
+   * own location from Oxlint; run Oxlint from the repository root or set
+   * the type explicitly. Set `monorepo` explicitly to change the layout
+   * globs.
+   */
+  repositoryType?: 'auto' | 'app' | 'library';
+}) | (Switches & MonorepoOptions & {
+  repositoryType: 'monorepo';
+});
+/**
+ * `defineConfig` from Oxlint for consumers who compose with `extends`.
+ *
+ * Oxlint only honors `ignorePatterns`, `env`, `globals`, and `settings` on
+ * the root config and drops them from extended configs. This wrapper folds
+ * those fields from every entry of `extends` into the root, and adds this
+ * package's ignore list. Prefer the second argument of `mkrz` when you only
+ * need to layer settings on this ruleset.
+ */
+declare function defineConfig(config: OxlintConfig): OxlintConfig;
+/**
+ * The complete ruleset as one flat root config.
+ *
+ * Everything is built as a single object rather than a chain of `extends`
+ * pieces: the plugin is declared once, the rule categories are declared once,
+ * and no subset can be handed to Oxlint that fails to load or runs at the
+ * wrong severity. `config` is the consumer's own root config and is layered
+ * on top: its root `rules` win over our root rules, its `overrides` run last,
+ * and its `ignorePatterns` are added to this package's list. Matching file
+ * overrides still take precedence over root rules.
+ */
+declare function mkrz(options?: MkrzOptions, config?: OxlintConfig): OxlintConfig;
+//#endregion
+export { type MkrzOptions, type MonorepoOptions, type RepositoryType, defineConfig, ignorePatterns, mkrz };