@noctcore/eslint-plugin-contracts 0.6.1 → 0.7.1

package/README.md

@@ -1,36 +1,73 @@
 # @noctcore/eslint-plugin-contracts
 
-Rules for shared **contract** conventions — zod schema naming, wire-message discriminants, error
-stringification, direct `process.env` access, and money precision. Flat-config only, ESLint 9+.
+Rules for shared **contract** conventions: zod schema naming, wire-message discriminants, error
+stringification, direct `process.env` access and money precision, where drift between producer and
+consumer breaks at runtime.
+
+**Docs:** [noctcore.github.io/eslint-plugins/packages/contracts](https://noctcore.github.io/eslint-plugins/packages/contracts/)
+
+Not a good fit for a codebase that does not use zod, or whose error handling is intentionally
+untyped.
+
+## Requirements
+
+- ESLint 9 or newer, flat config (`eslint.config.js`) only.
+- `configs.recommended` registers the plugin and sets rule severities, nothing else. It sets no
+  `files` and no parser, so it applies to whatever files the rest of your config lints. To lint
+  TypeScript, add a `files` pattern and `@typescript-eslint/parser`, as in the quick start.
 
 ## Install
 
 ```sh
-bun add -D @noctcore/eslint-plugin-contracts   # or npm i -D / pnpm add -D
+bun add -D @noctcore/eslint-plugin-contracts @typescript-eslint/parser   # or npm i -D / pnpm add -D
 ```
 
-## Use
+## Quick start
 
 ```js
 // eslint.config.js
+import tsParser from '@typescript-eslint/parser';
 import contracts from '@noctcore/eslint-plugin-contracts';
 
 export default [
-  contracts.configs.recommended,
+  {
+    ...contracts.configs.recommended,
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: { parser: tsParser },
+  },
+  // Optional: tune a preset rule's options.
+  {
+    files: ['**/*.{ts,tsx}'],
+    rules: {
+      'noctcore-contracts/zod-schema-naming': ['error', { roleSuffixes: ['Event', 'Command', 'Query'] }],
+      'noctcore-contracts/no-direct-process-env': ['error', { configModule: '@acme/config' }],
+    },
+  },
 ];
 ```
 
-Or wire rules individually:
+## Opt-in rules
 
-```js
-import contracts from '@noctcore/eslint-plugin-contracts';
+Four rules ship `off`: `require-registered-keys`, `env-var-schema-parity` and
+`translation-key-exists` do nothing until their `sinks` / `schema` / `catalogs` options are set, and
+`require-schema-parse-at-boundary` is a conservative syntactic slice of a type-aware concern.
 
+```js
+// eslint.config.js
 export default [
+  // ...the quick start's entries, then:
   {
-    plugins: { 'noctcore-contracts': contracts },
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: { parser: tsParser },
     rules: {
-      'noctcore-contracts/zod-schema-naming': ['error', { roleSuffixes: ['Event', 'Command', 'Query'] }],
-      'noctcore-contracts/no-direct-process-env': ['error', { configModule: '@acme/config' }],
+      'noctcore-contracts/require-registered-keys': ['error', {
+        sinks: [{ callee: 'localStorage.getItem', argIndex: 0 }],
+      }],
+      'noctcore-contracts/env-var-schema-parity': ['error', { schema: '.env.example' }],
+      'noctcore-contracts/translation-key-exists': ['error', {
+        catalogs: [{ file: 'locales/en/common.json', namespace: 'common' }],
+      }],
+      'noctcore-contracts/require-schema-parse-at-boundary': 'error',
     },
   },
 ];
@@ -38,24 +75,29 @@ export default [
 
 ## Rules
 
-Legend: 🔧 = autofixable · 💤 = ships inert / `off` in `recommended` (enable + configure explicitly).
-
-| Rule | Description | 🔧 | 💤 |
-| --- | --- | --- | --- |
-| [`zod-schema-naming`](./docs/rules/zod-schema-naming.md) | Exported zod schema must be a PascalCase `*Schema` const with a sibling `z.infer` type. | | |
-| [`wire-message-naming`](./docs/rules/wire-message-naming.md) | A role-suffixed schema's `type: z.literal(...)` must be kebab-case of its name minus the suffix. | 🔧 | |
-| [`no-error-stringify`](./docs/rules/no-error-stringify.md) | Ban `${error}` / `error.toString()` / `error + ""` — they drop the cause chain. | | |
-| [`no-direct-process-env`](./docs/rules/no-direct-process-env.md) | Ban direct `process.env`; require a typed config accessor. | | |
-| [`money-must-be-decimal`](./docs/rules/money-must-be-decimal.md) | Money-named fields typed `: number` are banned; require a Decimal money type. | | |
-| [`require-error-cause`](./docs/rules/require-error-cause.md) | Re-throwing a new error inside `catch` must forward the caught error as `{ cause }`. | 🔧 | |
-| [`restrict-throw-to-taxonomy`](./docs/rules/restrict-throw-to-taxonomy.md) | `throw` only allowlisted error classes; ban throwing non-Error values. | | |
-| [`require-registered-keys`](./docs/rules/require-registered-keys.md) | Key/name argument of a configured sink API must be an imported constant, not a raw string. | | 💤 |
-| [`env-var-schema-parity`](./docs/rules/env-var-schema-parity.md) | `process.env.FOO` / `import.meta.env.FOO` keys must be declared in a schema file. | | 💤 |
-| [`require-schema-parse-at-boundary`](./docs/rules/require-schema-parse-at-boundary.md) | Ban `JSON.parse(...) as T` / `(await res.json()) as T`; parse boundary data at runtime. | | 💤 |
-| [`schema-enum-field-consistency`](./docs/rules/schema-enum-field-consistency.md) | A field that is an enum in one zod object schema must not be `z.string()` in another schema of the same module. | | |
-| [`fetch-must-check-ok`](./docs/rules/fetch-must-check-ok.md) | A fetch response must be checked with `.ok` or a status comparison before `.json()` parses its body. | | |
-| [`translation-key-exists`](./docs/rules/translation-key-exists.md) | A static i18next / react-i18next key (`t(...)`, `i18n.t(...)`, `<Trans i18nKey>`) must exist in the catalog of the namespace in scope. | | 💤 |
-
-The 💤 rules ship `off` in `recommended`: `require-registered-keys`, `env-var-schema-parity` and
-`translation-key-exists` do nothing until their `sinks` / `schema` / `catalogs` options are set, and `require-schema-parse-at-boundary` is a
-conservative syntactic slice of a type-aware concern. Turn them on explicitly once configured.
+<!-- begin generated rules -->
+<!-- Generated by `bun run docs:readmes` from each rule's meta. Do not edit by hand. -->
+
+✅ in `recommended` (error) · ⚙️ needs options · 🔧 `--fix` · 💡 suggestions · 💭 needs type info · ❌ deprecated
+
+| Rule | Description | ✅ | ⚙️ | 🔧 | 💡 | 💭 |
+| --- | --- | :-: | :-: | :-: | :-: | :-: |
+| [`env-var-schema-parity`](https://noctcore.github.io/eslint-plugins/rules/contracts/env-var-schema-parity/) | Require every `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. |  | ⚙️ |  |  |  |
+| [`fetch-must-check-ok`](https://noctcore.github.io/eslint-plugins/rules/contracts/fetch-must-check-ok/) | Require a fetch response to be checked with `.ok` or a status comparison before `.json()` parses its body. | ✅ |  |  |  |  |
+| [`money-must-be-decimal`](https://noctcore.github.io/eslint-plugins/rules/contracts/money-must-be-decimal/) | Disallow monetary values typed as the JS primitive `number`. Money-named fields explicitly typed `: number` lose precision to float rounding; use a Decimal money type instead. | ✅ |  |  |  |  |
+| [`no-direct-process-env`](https://noctcore.github.io/eslint-plugins/rules/contracts/no-direct-process-env/) | Disallow direct `process.env` access. Force every consumer through a typed, validated config accessor so a missing variable fails at boot, not at use. | ✅ |  |  |  |  |
+| [`no-error-stringify`](https://noctcore.github.io/eslint-plugins/rules/contracts/no-error-stringify/) | Disallow stringifying an error with bare `${error}` interpolation, `error.toString()`, or `error + ""`. These drop the cause chain. Use `error instanceof Error ? error.message : String(error)` instead. | ✅ |  |  |  |  |
+| [`require-error-cause`](https://noctcore.github.io/eslint-plugins/rules/contracts/require-error-cause/) | Require re-thrown errors inside a `catch` to forward the caught error as `{ cause }`. A `throw new SomeError(...)` that omits the cause severs the chain to the original failure. | ✅ |  | 🔧 |  |  |
+| [`require-registered-keys`](https://noctcore.github.io/eslint-plugins/rules/contracts/require-registered-keys/) | Require the key/name argument of configured sink APIs (storage, event channels, cache keys) to be an imported constant from a registry module, not a raw string literal. |  | ⚙️ |  |  |  |
+| [`require-schema-parse-at-boundary`](https://noctcore.github.io/eslint-plugins/rules/contracts/require-schema-parse-at-boundary/) | Disallow asserting external boundary data with `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. |  |  |  |  |  |
+| [`restrict-throw-to-taxonomy`](https://noctcore.github.io/eslint-plugins/rules/contracts/restrict-throw-to-taxonomy/) | Restrict `throw` to an approved error taxonomy. Flags throwing a non-allowlisted error class and throwing a non-Error value (string, object, number, ...). | ✅ |  |  |  |  |
+| [`schema-enum-field-consistency`](https://noctcore.github.io/eslint-plugins/rules/contracts/schema-enum-field-consistency/) | Disallow a zod field that is an enum in one object schema of a module from being `z.string()` in another, which widens the wire type every consumer then narrows by hand. | ✅ |  |  |  |  |
+| [`translation-key-exists`](https://noctcore.github.io/eslint-plugins/rules/contracts/translation-key-exists/) | Require every static i18next / react-i18next translation key (`t(...)`, `i18n.t(...)`, `<Trans i18nKey>`) to exist in the catalog of the namespace in scope. |  | ⚙️ |  |  |  |
+| [`wire-message-naming`](https://noctcore.github.io/eslint-plugins/rules/contracts/wire-message-naming/) | A message-schema const ending in a role suffix (default Event/Command/Query) whose zod object declares `type: z.literal(...)` must set that literal to kebab-case(const name minus its role suffix). | ✅ |  | 🔧 |  |  |
+| [`zod-schema-naming`](https://noctcore.github.io/eslint-plugins/rules/contracts/zod-schema-naming/) | Every exported zod schema is a PascalCase const suffixed `Schema`, paired with a same-named inferred type (`export type Foo = z.infer<typeof FooSchema>`). | ✅ |  |  |  |  |
+<!-- end generated rules -->
+
+## Severity policy
+
+Every rule is `error` or `off`, never `warn`: a warning is a rule nobody obeys. See the
+[severity policy](https://noctcore.github.io/eslint-plugins/getting-started/#severity-policy).