@utilfirst/eslint-plugin

Shared rules for ESLint 10 and Oxlint.

Policy

Every exported rule must express universal project policy. The recommended config enables the complete registry at error severity, and the test suite rejects registry entries that are absent from that config. A rule that cannot justify universal error severity must be redesigned or removed rather than moved to an optional preset. Rule options adapt repository ownership or boundary conventions without disabling the rule.

Install

pnpm add -D @utilfirst/eslint-plugin

Use

// eslint.config.mjs
import utilfirst from "@utilfirst/eslint-plugin";

export default [
  utilfirst.configs.recommended,
  // ...your other configs
];

Configure

Rules with repository-specific ownership or boundary conventions accept options in either runtime. Apply option overrides after the recommended config so the rule stays enabled.

export default [
  utilfirst.configs.recommended,
  {
    rules: {
      "utilfirst/no-module-mocking": [
        "error",
        { internalModulePrefixes: ["@workspace/"] },
      ],
      "utilfirst/no-positional-boolean-parameters": [
        "error",
        { allowFunctionNames: ["protocolCallback"] },
      ],
      "utilfirst/no-unknown-parameters": [
        "error",
        { allowParameterNames: ["externalPayload"] },
      ],
      "utilfirst/prefer-options-parameter": [
        "error",
        { allowFunctionNames: ["protocolCallback"] },
      ],
    },
  },
];

• internalModulePrefixes marks package-style import prefixes as repository-owned for no-module-mocking.
• allowFunctionNames preserves named functions whose positional boolean or multi-input signature is fixed by an external protocol.
• allowParameterNames preserves unknown parameters whose names identify an externally fixed callback or interface signature.

// .oxlintrc.json
{
  "jsPlugins": [
    {
      "name": "utilfirst",
      "specifier": "@utilfirst/eslint-plugin",
    },
  ],
  "rules": {
    "utilfirst/consistent-blank-lines": "error",
    "utilfirst/no-chained-type-assertions": "error",
    "utilfirst/no-conditional-undefined-properties": "error",
    "utilfirst/no-enum-declarations": "error",
    "utilfirst/no-known-value-widening": "error",
    "utilfirst/no-module-mocking": [
      "error",
      { "internalModulePrefixes": ["@workspace/"] },
    ],
    "utilfirst/no-object-parameters": "error",
    "utilfirst/no-positional-boolean-parameters": [
      "error",
      { "allowFunctionNames": ["protocolCallback"] },
    ],
    "utilfirst/no-reflect-apply": "error",
    "utilfirst/no-reflect-get": "error",
    "utilfirst/no-unknown-parameters": [
      "error",
      { "allowParameterNames": ["externalPayload"] },
    ],
    "utilfirst/no-unknown-returns": "error",
    "utilfirst/no-unknown-type-aliases": "error",
    "utilfirst/no-unsafe-dictionary-type": "error",
    "utilfirst/no-unhandled-detached-promises": "error",
    "utilfirst/no-widen-then-assert": "error",
    "utilfirst/prefer-options-parameter": [
      "error",
      { "allowFunctionNames": ["protocolCallback"] },
    ],
    "utilfirst/prefer-switch-discriminator-chain": "error",
    "utilfirst/prefer-top-level-function-declarations": "error",
    "utilfirst/require-lint-suppression-reason": "error",
    "utilfirst/require-safety-comment-for-type-assertion": "error",
  },
}

Rules

docs/rules.md explains the policy boundary and expected replacement for every rule. The implementations and colocated tests remain the executable behavior owners.

Rule	Description
consistent-blank-lines	Apply tight, separate, or preserved gaps between statements and JSX children
no-chained-type-assertions	Reject chained TypeScript assertions
no-conditional-undefined-properties	Reject conditional undefined object properties
no-enum-declarations	Reject repository-owned enums other than ambient declarations
no-known-value-widening	Reject known values widened into broad target types
no-module-mocking	Reject Vitest and Jest mocking of repository-owned modules
no-object-parameters	Reject object function parameters
no-positional-boolean-parameters	Reject positional boolean flags on named functions and methods
no-reflect-apply	Reject Reflect.apply
no-reflect-get	Reject Reflect.get
no-unknown-parameters	Keep explicit unknown parameters at decoding boundaries
no-unknown-returns	Reject unknown return contracts
no-unknown-type-aliases	Reject type aliases that resolve to unknown
no-unsafe-dictionary-type	Reject dictionary contracts with broad value types
no-unhandled-detached-promises	Require rejection handling on void-marked detached call chains
no-widen-then-assert	Reject const flows that widen a known value before narrowing it
prefer-options-parameter	Require options objects for named functions and methods with three or more inputs
prefer-switch-discriminator-chain	Require a switch for four or more equality branches on one discriminator
prefer-top-level-function-declarations	Require declarations for direct top-level function bindings and default exports
require-lint-suppression-reason	Require a forcing reason on lint disable directives
require-safety-comment-for-type-assertion	Require one SAFETY: comment for each outermost non-const assertion

Attribution

The rules other than consistent-blank-lines, no-conditional-undefined-properties, no-enum-declarations, no-positional-boolean-parameters, no-unhandled-detached-promises, prefer-options-parameter, and require-lint-suppression-reason, along with their helpers, are adapted from dmmulroy/anti-slop under the MIT License. The package's LICENSE retains the copyright and permission notice.

Develop

pnpm install
pnpm run setup-hooks # one-time: wire pre-commit via simple-git-hooks
pnpm test            # unit, dual-runtime, and packed-artifact tests
pnpm run build       # tsdown → dist/
pnpm run lint        # oxlint + prettier + publint

License

MIT. The package includes third-party code under the same license.