@block65/oxlint-plugin

Opinionated oxlint rules for Block65 projects

Use

Through @block65/shared-config, which depends on this package, composes its groups with oxlint's own rules and resolves the plugin from wherever the config lives:

// oxlint.config.ts
import { defineConfig } from "@block65/shared-config/oxlint";

export default defineConfig({ ... });

This package holds the rules and, in groups, which of them belong together at what default level. Severities, combinations with other plugins and the formatter live in shared-config. A config that loads this plugin directly must sit where the bare specifier resolves, since oxlint reports a config it cannot load as a clean run.

Rules

Fixable with oxlint --fix.

comments

| Name                            | Description | 🔧 | | :------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :-- | | declaration-comments | Keep declaration comments in the form appropriate to their readers | 🔧 | | max-comment-lines | Limit a comment to the lines the code cannot carry itself | | | no-absence-comment | Disallow comment prose that states a fact as an absence | | | no-assumption-comment | Disallow comment prose that rests on an unverified premise | | | no-banned-comment-words | Disallow banned wording in comment prose | | | no-bare-block-comment | Disallow a block comment that is neither JSDoc nor a banner | 🔧 | | no-comment-divider | Disallow decorative separators in comments | 🔧 | | no-comment-history | Disallow comment prose that narrates a past state of the code | | | no-comment-list | Disallow an enumerated list inside a comment | | | no-comment-overclaim | Disallow an absolute in comment prose that a later change falsifies | | | no-comment-punctuation | Limit the colons and semicolons a comment joins its clauses with | | | no-figurative-comment | Disallow a physical verb or an idiom for an abstraction in comment prose | | | no-file-header-comment | Disallow a prose comment that opens the file | | | no-file-reference-in-comment | Disallow comment prose that names another source file | | | no-hedging-comment | Disallow comment prose that hedges on what the code does | | | no-jargon-comment | Disallow inflated wording in comment prose | | | no-jsdoc-on-statement | Disallow a JSDoc block on a statement or a local binding | 🔧 | | no-narrative-comment | Disallow comment prose that narrates instead of explaining | | | no-negated-comment | Limit comment prose that describes a subject by what it excludes | | | no-overconfident-comment | Disallow an adverb of certainty in comment prose | | | no-padded-comment | Disallow padded phrasing in comment prose | | | no-placeholder-comment | Disallow a comment standing where code should be | | | no-trailing-comment-punctuation | Disallow a closing punctuation mark on a comment | 🔧 | | require-comment-blank-line | Require a blank line above a comment that follows code | 🔧 |

clarity

| Name                            | Description | 🔧 | | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :-- | | function-style | Require a function declaration for a self-contained function, and a const arrow for one that closes over its surroundings | | | no-catch-annotation | Disallow a type annotation on a catch binding, which is already unknown | 🔧 | | no-delete | Disallow deleting a statically named property | | | no-double-assertion | Disallow one type assertion widening the operand of another | | | no-widening-object-annotation | Disallow an open dictionary annotation on a constant object literal | 🔧 | | no-explicit-return-type | Disallow a return type annotation the body already supplies | | | no-exported-function-bag | Prefer individual exports over exported objects grouping functions | | | no-filled-object-literal | Disallow filling an object literal by computed key after declaring it | | | no-function-component-annotation | Disallow typing a component through a function component alias | | | no-flat-map-filter | Disallow a flatMap branch that returns an empty array | | | no-hardcoded-url | Disallow a hardcoded origin where a request is made | | | no-interpolated-url-path | Disallow a URL template that interpolates straight onto its host | | | no-negated-state | Disallow comparing a state field by negation | | | no-nested-await | Disallow an await expression as a call argument | | | no-pascal-case-variable | Disallow a PascalCase name on a variable that holds a value | | | no-reserved-tld | Disallow a URL host in a reserved top-level domain | | | no-sentinel-fallback | Disallow an empty-value fallback on a nullish coalesce | | | no-single-character-declaration | Disallow a single-character name on a declared variable | | | no-single-use-function | Disallow a module-scope function called exactly once | | | no-tensed-time-field | Require a tenseless Time suffix on a time-valued column | | | no-try-assignment | Disallow assigning an empty declaration from inside a try | | | no-union-from-value | Disallow a type read off a value nothing checks | | | prefer-largest-duration-unit | Disallow a duration written in a finer unit than it divides into | | | prefer-type-for-data | Prefer a type alias over an interface that holds only data | 🔧 | | require-camel-case-parameter | Require camelCase on a parameter name the function chooses | | | require-mock-import | Require a module mock to name its module through import() | | | require-namespace-import | Require a namespace import from modules whose keys carry their meaning | | | require-pascal-case-type | Require PascalCase on a type, interface, enum or class declaration | | | require-predicate-prefix | Require a predicate to be named with is, has, should or can | | | require-statement-blank-line | Require a blank line before a control statement and after a block | 🔧 |

pedantic

| Name | Description | | :--------------------------------------------------------------------- | :-------------------------------------------- | | require-t-prefixed-generic | Require a type parameter name to start with T |

baseline

| Name                | Description | 🔧 | | :------------------------------------------------------- | :------------------------------------------------------------------------- | :-- | | no-non-baseline-api | Disallow an unguarded reference to an API below Baseline widely available | | | no-non-baseline-css | Disallow a vanilla-extract style using CSS below Baseline widely available | |

http

| Name | Description | 🔧 | | :--------------------------------------------- | :--------------------------------------------------------- | :-- | | prefer-req-res | Require req and res for HTTP request and response bindings | |

valibot

| Name                  | Description | 🔧 | | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :-- | | no-any-schema | Disallow the valibot any schema | 🔧 | | no-conflicting-pipe-actions | Disallow bounds in a valibot pipe that no input can satisfy | | | no-needless-async | Disallow the async form of a valibot function around sync schemas | 🔧 | | no-schema-from-entries | Disallow rebuilding a valibot object schema from another schema's entries alone | | | no-transform-in-record-key | Disallow rewriting the keys of a valibot record schema | | | no-sync-parse-on-async-schema | Disallow a synchronous parse of an asynchronous schema | 🔧 | | no-unknown-coercion | Disallow coercing unknown input in a valibot pipe | | | prefer-exact-optional | Require exactOptional over optional for valibot object entries | | | prefer-safe-parse | Prefer safeParse over a valibot parse that would throw uncaught | | | prefer-strict-object | Prefer strictObject over the object and looseObject valibot schemas | | | prefer-variant | Prefer variant over union for objects that share a literal key | 🔧 | | require-async-wrapper | Require the async form of a valibot function that wraps an async schema | 🔧 | | require-length-with-id-action | Require a length action alongside nanoid or cuid2 | | | require-union-options | Require two or more options in a valibot union | 🔧 | | snake-case-wire-keys | Require snake_case keys on objects that cross the wire | | | valibot-schema-suffix | Require a suffix on bindings holding a valibot schema | |

vanilla-extract

Rules about vanilla-extract itself, so any project using the library can take them.

| Name | Description | 🔧 | | :------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :-- | | no-unitless-length | Disallow a bare number on a vanilla-extract property that takes a length | | | prefer-logical-properties | Prefer inline-axis logical properties over their left and right equivalents | | | require-reduced-motion | Require a prefers-reduced-motion guard beside a transition or animation | | | no-transition-all | Disallow transitioning all rather than the properties that change | | | no-invalid-declaration | Disallow a vanilla-extract declaration a browser would drop as invalid CSS | |

design-system

Left out of shared-config's standard. These rules recommend design-system props and tokens that do not all exist yet, so enable them on application styles and read their reports as a migration worklist.

| Name | Description | 🔧 | | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :-- | | prefer-layout-primitives | Prefer Block65 layout primitives over repeated vanilla-extract flex layouts | | | no-raw-spacing | Prefer a design-system spacing token over a raw length in a vanilla-extract style | |

pilot

Left out of shared-config's standard until the hits on real code are seen.

| Name | Description | | :--------------------------------------------------------- | :----------------------------------------------------------------------- | | prefer-builtin-async | Prefer the promise form of a Node builtin over its callback or sync form |

Options

"block65/no-non-baseline-api": ["warn", { baseline: "newly", allow: ["temporal"] }],

baseline is "widely" or "newly"; allow lists API names or web-features ids. no-non-baseline-css takes the same options for CSS names.

"block65/no-jargon-comment": ["warn", { allow: ["leverage"] }],

Each wording rule and each naming rule takes allow, the keys its reports quote.

"block65/no-pascal-case-variable": ["warn", { components: false }],

components leaves a PascalCase name in a .tsx or .jsx file alone; default on, also on require-camel-case-parameter.

"block65/prefer-layout-primitives": ["warn", { includeMixed: true }],

includeMixed also reports a style whose layout declarations sit beside ones that must stay in CSS, and names which to keep; default off.

Unicorn rules oxlint has not ported

jsPlugins: ["@block65/oxlint-plugin", "@block65/oxlint-plugin/unicorn-unported"],
rules: {
	"unicorn-unported/comment-content": "warn",
	"unicorn-unported/prefer-regexp-escape": "warn",
	"unicorn-unported/prefer-temporal": "warn",
	"unicorn-unported/prefer-uint8array-base64": "warn",
},