@aurelienbbn/oxlint-plugin-core

18 oxlint rules for any TypeScript codebase: swallowed errors, flaky or hollow tests, test code in production, anonymous public contracts, workspace members that leak into each other, cramped statements.

pnpm add -D @aurelienbbn/oxlint-plugin-core oxlint   # oxlint >=1.82.0 <2.0.0

{
  "jsPlugins": ["@aurelienbbn/oxlint-plugin-core"],
  "rules": {
    "core/no-discarded-caught-error": "error",
    "core/no-weak-test-assertions": ["error", { "assertionHelpers": ["assertValid"] }],
    "core/no-test-sleeps": "error"
  }
}

No preset, one kind of autofix. Enable each rule by name; every fix but the padding rules' blank lines needs a decision a tool can't make.

🧯 A caught error is handled or explained

try {
  await sync();
} catch (error) {
  console.error(error);
  return [];
} // ❌ only logged
promise.catch(() => null); // ❌ discarded
promise.catch(handleFailure); // ✅ handed to a function
try {
  access(path);
  return true;
} catch {
  // REASON: a missing file is the negative answer here
  return false; // ✅ reasoned
}

return err.message === "Not found"; // ❌ no-error-message-matching
return error instanceof TimeoutError; // ✅ class, tag, or code

try {
  return await load(id);
} catch (error) {
  throw new LoadError({ id, cause: error });
} // ✅ rethrown
try {
  return await load();
} catch (error) {
  if (isNotFound(error)) return undefined;
  throw error;
} // ✅ inspected

🧪 A test proves behavior, deterministically

no-weak-test-assertions judges per test: one strong assertion clears it.

await new Promise((r) => setTimeout(r, 500)); // ❌ no-test-sleeps
await vi.waitFor(() => expect(state()).toBe("done")); // ✅ poll the condition

// cart.test.ts
vi.spyOn(cart, "total").mockReturnValue(30); // ❌ no-stubbed-subject
vi.spyOn(pricing, "rate").mockReturnValue(2); // ✅ another module

export const send = (mail) => (process.env.NODE_ENV === "test" ? undefined : deliver(mail)); // ❌ no-test-logic-in-production

Projects using Vitest in-source testing turn no-test-logic-in-production off for those files.

await new Promise((r) => setTimeout(r, 500)); // ❌ timer-only executor
import { setTimeout as sleep } from "node:timers/promises"; // ❌ also `scheduler`
await sleep(250); // ❌ sleep / delay / wait / pause + numeric literal

import * as cart from "./cart"; // also ./cart.js, ../cart/index
vi.spyOn(cart, "total"); // ✅ pass-through spy

export const send = (mail) => (process.env.NODE_ENV === "test" ? undefined : deliver(mail)); // ❌ also import.meta.env.MODE === "test"
export const retries = process.env.VITEST ? 0 : 3; // ❌ also VITEST_WORKER_ID, JEST_WORKER_ID, import.meta.vitest
export const __testing__ = { parse }; // ❌ name marks it test-only
/** Visible only for unit tests. */
export const parse = (input) => input; // ❌ comment marks it test-only

📜 Public contracts are named

export const getUser = () => ({ id: user.id }); // ❌ no-exported-anonymous-object-return
export const load: Load = () => ({ id: user.id }); // ✅ named contract

const loadUser = (userId: UserId, includePosts: boolean) => userId; // ❌ no-multi-positional-parameters
export function loadUser(input: { userId: UserId; includePosts: boolean }) {} // ✅ object input

export let currentUserId = undefined; // ❌ no-mutable-exported-state
export * from "./user.js"; // (whole file)                    // ❌ no-reexport-only-modules, unless listed in `allow`
let total = 0; // ❌ no-let (also `var`)

🧱 Workspace members meet only through their exports

workspace-boundaries reads the members of the nearest pnpm-workspace.yaml (or package.json workspaces) and judges every import, export … from, and import() between two members:

// packages/kernel/src/tick.ts
import { boot } from "@game/client"; // ❌ packages never import apps (members under `apps`)
import { arrow } from "../../ranger/src/arrow.ts"; // ❌ relative path into another member
import { body } from "@game/physics/src/body.ts"; // ❌ not opened by @game/physics `exports`
import { body } from "@game/physics"; // ✅ an exported subpath

{
  "core/workspace-boundaries": [
    "error",
    {
      "apps": ["apps/**", "infra/**"],
      "forbidden": [
        { "from": "packages/features/*", "to": "packages/features/*", "message": "features meet through the kernel" },
        { "from": "packages/kernel", "to": "packages/adapters/**" }
      ]
    }
  ]
}

A manifest without subpath exports opens only its root; a subpath mapped to null stays closed; * matches at least one character, as in Node. Type-only imports and re-exports are judged like value imports: a type dependency is still a dependency. require() and import x = require() are not read. Files outside every member (root configs, scripts) are never judged. Directory patterns: * within one segment, ** across segments. Members are read once per lint process: restart an editor's language server after adding one. Cycles stay with import/no-cycle, dead files with Knip.

💬 Comments describe code, not its history

// Updated to use the new pricing API    ❌ change narration (line comments)
// TODO: rename this contract            ❌ untracked
// TODO(#123): rename this contract      ✅ tracked (also CART-42 or a link)
/** Updated when the cache expires */    ✅ docblock describing behavior

↕️ Blocks, declaration runs and exits stand apart

padding-line-between-statements takes ESLint's options (a list of { blankLine, prev, next }, the last match wins) and its statement types. A comment block above a statement belongs to it: the blank line goes above the comments, and a comment on the line a statement ends on stays with that statement. Autofix inserts or removes the blank lines.

function start(runtime) {
  const config = load();
  // Planning runs need no config.
  if (runtime.planning) {
    return;
  }
  runtime.apply(config); // ❌ twice: above the comment, and below the block
}

function start(runtime) {
  const config = load();

  // Planning runs need no config.
  if (runtime.planning) {
    return;
  }

  runtime.apply(config); // ✅
}

Enabled without options, it applies this configuration; any options replace it whole:

{
  "core/padding-line-between-statements": [
    "error",
    { "blankLine": "always", "prev": "*", "next": ["block-like", "multiline-expression"] },
    { "blankLine": "always", "prev": ["block-like", "multiline-expression"], "next": "*" },
    { "blankLine": "always", "prev": ["const", "let"], "next": "*" },
    { "blankLine": "any", "prev": ["const", "let"], "next": ["const", "let"] },
    { "blankLine": "always", "prev": "*", "next": ["return", "throw"] }
  ]
}

⚠️ Migration

Registered contract inventory

Generated from package exports by pnpm catalog. Rule-specific options and limitations are described above and in the source tests.

Credited concepts

• "Eradicating Non-Determinism in Tests" by Martin Fowler (concept)
• "Test Logic in Production" (G. Meszaros, xUnit Test Patterns) (concept)
• KeepCart/app tools/workspace-boundaries (same author; generalised with configurable apps and a forbidden-import matrix)
• code-slop by asyrafhussin (MIT, concept re-implemented)
• code-slop by asyrafhussin (MIT, concept re-implemented) — closing-brace labels and placeholder
• https://eslint.org/docs/latest/rules/padding-line-between-statements (MIT; concept, independently implemented)
• https://eslint.org/docs/latest/rules/padding-line-between-statements (MIT; option schema and statement types, independently implemented)