@noctcore/eslint-plugin-contracts
A bad fit if you do not use zod, or if your error handling is intentionally untyped.
IO boundaries (checked fetch responses, parsed boundary data), error taxonomy, schema and wire naming, env access, money precision and translation keys.
What it solves
Section titled “What it solves”The places a system talks to the outside world are where types stop being true: a fetch whose body is parsed without checking .ok, a JSON.parse(...) as User, an error re-thrown without its cause, process.env.FOO read in forty places, money typed as a float. These rules hold the contract layer to conventions that make those boundaries explicit and checkable.
What it will yell at you about
Section titled “What it will yell at you about”It will yell at you about naming and boundary discipline: zod schemas must be PascalCaseSchema with a paired inferred type, wire messages need a literal type discriminant, process.env goes through one config module, thrown errors come from an approved taxonomy. Several conventions are opinionated, and the naming rules assume zod. It is a bad fit if you do not use zod, or if your error handling is intentionally untyped. Nine rules ship off: five are inert until you give them a sink list, schema file, translation catalogs, route groups or an auth map (route-handler-order enforces one middleware order in route chains, for example docs, auth and validation before the handler, and describe-auth-matches-middleware checks that the auth kind a route docs call declares matches the middleware in its chain), restrict-throw-to-taxonomy reports every exception until allow names your error classes, require-schema-parse-at-boundary is a conservative syntactic slice of a concern a type-aware setup does better, route-params-validated (reports a route with :name segments and no param validator in its chain) matches routers and param validators by name, and zod-field-describe is a documentation convention you enable for the schema modules that feed a generator.
Install and configure
Section titled “Install and configure”npm install --save-dev @noctcore/eslint-plugin-contracts @typescript-eslint/parser# or: bun add -D / pnpm add -D @noctcore/eslint-plugin-contracts @typescript-eslint/parserThe recommended preset enables 6 of 17 rules. The strict preset adds 2 house rules (naming, folder shape, size caps) on top. The rules board below builds the flat config: start from a preset, switch single rules between error and off, and copy the result.
Each rule links to its page, with the options it takes and Incorrect and Correct examples. A good first
read is fetch-must-check-ok.
--fixsuggestionsneeds optionstype infoEach switch sets a rule to error or off.
process.env.FOO / import.meta.env.FOO key to be declared in a schema file (.env.example or a zod-env module), so config access and config declaration cannot drift apart..ok or a status comparison before .json() parses its body.number. Money-named fields explicitly typed : number lose precision to float rounding; use a Decimal money type instead.process.env access. Force every consumer through a typed, validated config accessor so a missing variable fails at boot, not at use.${error} interpolation, error.toString(), or error + "". These give "Error: <message>" or "[object Object]". Use error instanceof Error ? error.message : String(error) instead.catch to forward the caught error as { cause }. A throw new SomeError(...) that omits the cause severs the chain to the original failure.as T instead of parsing it at runtime. Flags casts of JSON.parse, res.json(), web storage, URL search params, message-event data and LLM tool input, directly or through a const; use a zod/valibot parse.throw to an approved error taxonomy. Flags throwing a non-allowlisted error class and throwing a non-Error value (string, object, number, ...).:name parameters to carry a param validator in its handler chain.z.string() in another, which widens the wire type every consumer then narrows by hand.t(...), i18n.t(...), <Trans i18nKey>) to exist in the catalog of the namespace in scope.type: z.literal(...) must set that literal to kebab-case(const name minus its role suffix)..describe() or .meta({ description }), so generated JSON Schema, tool definitions and API docs have text for each field.Schema, paired with a same-named inferred type (export type Foo = z.infer<typeof FooSchema>).