@mkrz/oxlint-config 0.1.0

package/docs/performance.md

@@ -0,0 +1,29 @@
+# Consumer benchmark
+
+Run `pnpm run benchmark` to build the package and lint a temporary TypeScript
+service fixture with type awareness disabled and enabled. The script removes
+the fixture afterward and prints JSON with the machine details and every
+measurement. It requires the development peers, including `oxlint-tsgolint`.
+
+The fixture contains 200 modules and 5,200 lines of typed account records,
+array filtering, aggregation, async loading, and string derivation. It runs
+the built package with `react: false` and the application policy. Every lint
+run must exit successfully. Each mode gets one warmup followed by five
+measurements, with four lint threads. Each measurement starts a new Node and
+Oxlint process, so startup, plugin loading, and type-service startup are
+included. Filesystem caches are warm after the first run.
+
+Measured on 2026-09-04 with Node 24.18.0, Oxlint 1.81.0, oxlint-tsgolint
+7.0.2001, Linux x64, and an AMD Ryzen 5 PRO 5650G:
+
+| Type awareness | Runs in milliseconds    | Median |
+| -------------- | ----------------------- | ------ |
+| Disabled       | 234, 227, 242, 223, 230 | 230 ms |
+| Enabled        | 327, 340, 358, 390, 325 | 340 ms |
+
+Type awareness added 110 ms to the median on this fixture. This is a
+synthetic service workload with repeated module structure. It does not
+measure React applications, third-party type complexity, monorepo import
+graphs, editor latency, or large volumes of diagnostics. Measure those in
+an actual consumer before using these numbers to set a CI budget. The script
+is a repeatable baseline, not a performance guarantee or a timing test in CI.

package/docs/rules.md

@@ -0,0 +1,190 @@
+# Custom rule reference
+
+All custom rules run at error severity when their concern is enabled.
+Examples show the syntax relevant to each rule; other rules may impose
+additional requirements. Query and bound-store names follow the conventions
+in the README, without resolving aliases or wrapper implementations.
+
+## no-app-requires
+
+Shared packages must not require applications listed in `appPackages`.
+Rejects `require('@acme/web/private')` and `module.require('@acme/web')` when
+`@acme/web` is an application. Move the implementation to a shared package,
+then use `require('@acme/shared')`. Options are one array of gitignore-style
+module patterns. The monorepo config supplies these automatically, including
+subpaths. Local functions named `require` and local objects named `module`
+are exempt. Only static string and expression-free template arguments can
+be checked.
+
+## no-let
+
+Rejects `let total = 0` and `for (let i = 0; i < items.length; i++)`.
+Use `const total = items.reduce((sum, item) => sum + item.price, 0)` for an
+aggregate, or `for (const item of items)` for iteration. Mutation of objects
+is a separate policy; this rule only rejects `let` declarations.
+
+## no-oxlint-disable
+
+Applications reject Oxlint and ESLint disable comments. Fix the reported
+code or configure an explicit file override at the repository root.
+For example, replace a disabled `no-alert` violation with the application's
+notification UI. Self-suppression of this rule remains a limitation of
+in-process lint rules; see the README before treating this as enforcement
+against deliberate bypasses.
+
+## package-disable-policy
+
+Libraries permit one named rule on a next-line Oxlint directive with a reason:
+
+```ts
+// oxlint-disable-next-line no-alert -- Browser adapter intentionally uses a native dialog.
+alert(message);
+```
+
+Rejects broad `/* oxlint-disable */`, ESLint directives, multiple rules, and
+missing reasons. Prefer a code fix; when the exception is a repository policy,
+put it in a matching config override. Unused directives are errors too.
+
+## no-query-result-destructuring
+
+Rejects `const { data } = useUserQuery()` and
+`const { mutate } = useMutation(options)`. Use `const query = useUserQuery()`
+and `query.data`, or `const mutation = useMutation(options)` and
+`mutation.mutate(input)`. Keeping fields qualified is a project convention.
+Modern TypeScript can preserve discriminant narrowing in a single `const`
+destructuring declaration; the rule also rejects that valid form.
+
+## no-restricted-react-hooks
+
+Rejects React's `useEffect`, `useLayoutEffect`, `useInsertionEffect`,
+`useMemo`, `useCallback`, `useReducer`, and `useSyncExternalStore`.
+Imported aliases and React namespace/default imports are checked by binding.
+Unrelated local functions with the same names are exempt.
+
+Derive values during render instead of copying props into effect-managed
+state. Put user-triggered work in event handlers. Use query hooks for server
+state and selector-based store hooks for shared client state. Let React
+Compiler handle memoization when it is configured in the build; installing
+this lint package does not enable the compiler.
+
+A DOM integration or subscription with no suitable library abstraction may
+need an explicit repository-level exception. This policy does not imply that
+React's effect APIs are inherently incorrect, or that an event handler can
+replace every effect.
+
+## require-store-selector
+
+Rejects `useCartStore()`, `useCartStore(undefined)`, and
+`useCartStore((state) => state)`. Use
+`useCartStore((state) => state.total)`. For a bare Zustand hook, use
+`useStore(cartStore, (state) => state.total)`.
+
+The first argument is the selector for domain-named bound hooks; the second
+is the selector for `useStore` imported from `zustand` or `zustand/react`.
+The rule also detects `void` arguments and simple inline identity functions.
+It cannot prove what an arbitrary selector identifier returns.
+
+## no-type-assertion
+
+Rejects `payload as User` and `<User>payload`; allows `as const`.
+Validate external input with a schema, such as `const user = UserSchema.parse(payload)`,
+or narrow it with a type guard. `satisfies` checks a value's shape without
+asserting its type. Test files permit type assertions.
+
+## no-chained-type-assertions
+
+Rejects `payload as unknown as User`, including chains separated by `!`.
+Use a parser or type guard to establish the target type. Test files permit
+assertions, including chains used to construct deliberate invalid inputs.
+
+## no-known-value-widening
+
+Rejects erasing a known value into a broad contract, such as
+`const value: unknown = { id: 1 }`. Prefer `const value = { id: 1 }`, or a
+named domain contract that describes the value. Type parameters and locally
+shadowed declarations do not resolve to unrelated module aliases. This rule
+is relaxed in test files.
+
+## no-module-mocking
+
+Rejects `vi.mock('./client')`, `jest.mock('./client')`, and the related
+module-mocking methods. Pass a dependency through a function argument or
+constructor instead. For example, call `loadUser(fakeClient, id)` in a test
+when production calls `loadUser(httpClient, id)`. Unrelated local objects
+named `vi` or `jest` are exempt. This rule remains active in test files.
+
+## no-reflect-apply
+
+Rejects `Reflect.apply(handler, receiver, args)`. Call
+`handler.call(receiver, ...args)` when the receiver matters, or
+`handler(...args)` for an ordinary function. A locally shadowed `Reflect`
+is not the builtin and is exempt.
+
+## no-reflect-get
+
+Rejects `Reflect.get(user, 'name')`. Use `user.name` or a typed index access
+such as `user[key]`. Validate external shapes before reading their fields.
+A locally shadowed `Reflect` is exempt.
+
+## no-unknown-parameters
+
+Rejects ordinary parameters annotated with bare `unknown`, such as
+`function save(input: unknown)`. Accept a domain type, or let a schema
+library handle untrusted input. Type guards may accept an unknown value
+when their predicate narrows that parameter:
+
+```ts
+function isName(input: unknown): input is string {
+  return typeof input === 'string';
+}
+```
+
+An explicit `this` parameter is exempt. The rule checks bare annotations,
+not all types that could resolve to unknown.
+
+## no-unknown-returns
+
+Rejects explicit `unknown`, aliases resolving to unknown, and builtin
+`Promise<unknown>` return contracts. Prefer `Promise<User>` after validating
+the response. A locally defined or imported type named `Promise` does not
+mean the builtin. This is a syntactic contract check, not full inference of
+all possible return types.
+
+## no-unknown-type-aliases
+
+Rejects `type Payload = unknown`. Replace the placeholder with a domain
+contract, for example `type Payload = { id: string }`, or keep untrusted
+input inside the parsing boundary. Union members and supported module aliases
+are followed; shadowed local bindings remain distinct.
+
+## no-unsafe-dictionary-type
+
+Rejects open dictionaries with unsafe values, such as `Record<string, unknown>`.
+Use a named value contract, such as `Record<string, User>`. A mapped type over
+a closed key set, `keyof` inspection, and indexed access are treated differently
+from an open dictionary. Local aliases named `Readonly` or other builtin
+wrappers are not assumed to have the builtin meaning.
+
+## no-widen-then-assert
+
+Rejects first erasing information and then asserting it back, such as
+`const widened: unknown = user; const restored = widened as User`.
+Keep `user` with its original inferred type or validate data at an external
+boundary. This rule is relaxed in test files.
+
+## padding-line-between-statements
+
+The default policy requires blank lines after multiline statements and
+blocks, and before `return`. Consecutive imports are exempt:
+
+```ts
+function total(items: Item[]) {
+  const value = items.reduce((sum, item) => sum + item.price, 0);
+
+  return value;
+}
+```
+
+Run `oxlint --fix` to insert or remove whitespace. Options follow ESLint
+Stylistic's `blankLine`, `prev`, and `next` format. The `selector` option
+accepts `*` or an exact AST node type, not arbitrary esquery selectors.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@mkrz/oxlint-config",
+  "version": "0.1.0",
+  "description": "Opinionated Oxlint ruleset for TypeScript and React",
+  "keywords": [
+    "lint",
+    "linting",
+    "oxlint",
+    "oxlint-config",
+    "react",
+    "typescript"
+  ],
+  "homepage": "https://github.com/mkrz/oxlint-config#readme",
+  "bugs": {
+    "url": "https://github.com/mkrz/oxlint-config/issues"
+  },
+  "license": "MIT",
+  "author": "Michael Kreuzmayr",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mkrz/oxlint-config.git"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.anti-slop",
+    "LICENSE.stylistic",
+    "README.md",
+    "docs"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "default": "./dist/plugin/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ignore": "^7.0.8"
+  },
+  "devDependencies": {
+    "@oxlint/plugins": "~1.81.0",
+    "@types/node": "22.20.1",
+    "oxfmt": "0.66.0",
+    "oxlint": "~1.81.0",
+    "oxlint-tsgolint": "~7.0.2001",
+    "tsdown": "0.22.14",
+    "tsx": "4.23.13",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@oxlint/plugins": "~1.81.0",
+    "oxlint": "~1.81.0",
+    "oxlint-tsgolint": "~7.0.2001"
+  },
+  "peerDependenciesMeta": {
+    "oxlint-tsgolint": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "benchmark": "pnpm run build && node scripts/benchmark.ts",
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "test": "tsx src/test.ts",
+    "test:pack": "bash scripts/pack-test.sh",
+    "test:update-policy": "node --env-file=scripts/update-policy.env --import tsx src/policy.test.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build"
+  }
+}