@nojaf/oxlint-plugin-annotate-non-primitives

An oxlint plugin with a single rule: write down the type whenever it isn't obvious from the initializer.

Inference is convenient while writing code and unhelpful while reading it. This rule keeps the shorthand where the type is already staring at you (literals, comparisons, casts) and asks for an annotation everywhere else.

Install

bun add -d @nojaf/oxlint-plugin-annotate-non-primitives
npm install --save-dev @nojaf/oxlint-plugin-annotate-non-primitives

Configure

Add the package to jsPlugins and switch the rule on in .oxlintrc.json:

{
  "jsPlugins": ["@nojaf/oxlint-plugin-annotate-non-primitives"],
  "rules": {
    "nojaf/annotate-non-primitives": "error"
  }
}

The rule lives under the nojaf namespace. To use a different one, give the plugin an alias:

{
  "jsPlugins": [
    {
      "name": "house-style",
      "specifier": "@nojaf/oxlint-plugin-annotate-non-primitives"
    }
  ],
  "rules": {
    "house-style/annotate-non-primitives": "error"
  }
}

What the rule does

Variable declarations

const and let declarations need an annotation unless the initializer makes the type obvious.

Allowed as-is:

const answer = 42;
const greeting = "hello";
const enabled = true;
const template = `hello ${greeting}`;
const remainder = answer % 60;
const padded = remainder < 10 ? "0" : "1";
const top = expr as Pixels;
const schema = z.object({ name: z.string() });

Reported:

const rect = el.getBoundingClientRect();
const acc = [];
const node = nodes[i]!;
const body = document.body;
const double = (value: number): number => value * 2;

Destructuring patterns (const { a } = obj) and declarations without an initializer (let x;) are skipped — the first has no single name to annotate, the second is already annotated or genuinely untyped.

Arrow function parameters

Every identifier parameter of an arrow function needs a type annotation:

items.map((value) => value.length); // reported
items.map((value: string) => value.length); // fine

Requirements

• oxlint 1.x with JS plugins enabled (JS plugins are alpha and not subject to semver).
• Node.js 18+ for the published build (plain ESM, no runtime dependencies).

Development

bun install
bun test        # runs oxlint over test/fixtures and asserts the diagnostics
bun run lint    # the plugin lints its own source
bun run typecheck
bun run build   # emits dist/

To inspect the AST oxlint hands to the rule:

echo 'const x = foo();' | bun run scripts/ast.ts

The oxc AST can differ from what you would expect from ESTree, so check the real node shape before matching on it.

License

MIT