@noctcore/eslint-plugin-contracts 0.6.1 → 0.7.1

package/docs/rules/money-must-be-decimal.md

@@ -2,6 +2,10 @@
 
 > Monetary fields typed as the JS `number` primitive lose precision to float rounding — use a Decimal money type.
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 Money stored as a JS `number` accumulates IEEE-754 rounding errors (`0.1 + 0.2 !== 0.3`), which is
@@ -16,10 +20,6 @@ positions that carry real precision risk:
 - class properties — `class Invoice { total: number }`
 - annotated variable declarators — `const amount: number = …`
 
-Conservative on purpose. Untyped declarations and numeric-literal initializers (`let total = 0`) are
-**not** flagged — those are usually counters/accumulators. Interface and type-literal members
-(`{ amount: number }`) are **out of scope** so non-money type members do not regress.
-
 ```ts bad reports=2
 class Invoice { total: number; }
 const amount: number = 5;
@@ -31,6 +31,15 @@ const count: number = 3;          // not a money name
 interface Payment { amount: number; }   // type member, out of scope
 ```
 
+## What it does not flag
+
+Conservative on purpose. Untyped declarations and numeric-literal initializers (`let total = 0`) are
+**not** flagged — those are usually counters/accumulators. Interface and type-literal members
+(`{ amount: number }`) are **out of scope** so non-money type members do not regress.
+
+- Object-literal properties (`const x = { total: 5 }`).
+- Fields matching `minorUnitPatterns`, and every field in a file listed in `allowedFiles`.
+
 ## Options
 
 | Option | Type | Default | Meaning |
@@ -47,7 +56,7 @@ interface Payment { amount: number; }   // type member, out of scope
 }]
 ```
 
-## Talking to a payment API
+### Talking to a payment API
 
 Stripe and most payment APIs deal in integer minor units: `amount` is a number of cents, and that
 is correct at that boundary. Without `minorUnitPatterns` this rule flags every one of those

package/docs/rules/no-direct-process-env.md

@@ -2,6 +2,10 @@
 
 > Read environment variables through a typed, validated config accessor — never `process.env` directly.
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 `process.env.X` is `string | undefined`, unvalidated, and reachable from anywhere. A typo or a missing
@@ -27,8 +31,12 @@ import { config } from '@/config';
 const isProd = config.isProduction;
 ```
 
-Files matched by the `allowedFiles` glob allowlist are skipped entirely, so bootstrap entrypoints,
-config files, and tests may still read `process.env` directly.
+## What it does not flag
+
+- Files matched by the `allowedFiles` glob allowlist are skipped entirely, so bootstrap entrypoints,
+  config files, and tests may still read `process.env` directly.
+- `import.meta.env` reads and other `process` properties (`process.environment`, `process.argv`):
+  only `process.env` itself is policed.
 
 ```ts good filename=vite.config.ts relocation
 const isProd = process.env.NODE_ENV === 'production';

package/docs/rules/no-error-stringify.md

@@ -2,6 +2,10 @@
 
 > Stringifying an error with `${error}`, `error.toString()`, or `error + ""` drops its cause chain.
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 `` `${error}` ``, `error.toString()`, and `error + ""` all coerce an `Error` to its `message` alone,
@@ -31,6 +35,12 @@ const msg = error instanceof Error ? error.message : String(error);
 const m = `${error.message}`;
 ```
 
+## What it does not flag
+
+- Bare `String(error)`, which the guarded extractor idiom relies on.
+- Member reads such as `` `${error.message}` `` or `error.stack`.
+- `x + ""` where `x` is not one of `errorIdentifierNames` (`count + ""`).
+
 ## Options
 
 | Option | Type | Default | Meaning |

package/docs/rules/require-error-cause.md

@@ -2,6 +2,10 @@
 
 > Re-throwing inside a `catch` without `{ cause }` severs the chain to the original error. 🔧
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 🔧 Fixable with `--fix` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 When you catch an error and throw a new one, the new error is what reaches your logger. If you do not
@@ -20,16 +24,6 @@ try {
 ## What it flags
 
 A `throw new SomeError(...)` inside a `catch` block when **no** argument carries a `cause` property.
-Deliberately conservative:
-
-- Only constructors whose simple name ends in `Error` or `Exception` are treated as errors
-  (`Error`, `TypeError`, `ValidationError`, `HttpException`). Throwing `new Response(...)` for
-  control flow is not policed.
-- Fires only when the enclosing catch binds a plain identifier (`catch (err)`). A parameterless
-  `catch {}` or a destructured binding (`catch ({ message })`) has no single name to attach, so the
-  throw is left alone.
-- Any `cause` property (whatever its value), and any spread the rule cannot see through, counts as
-  "has a cause" and suppresses the report — a hand-written cause is never second-guessed.
 
 A `throw` nested in a closure declared inside the catch is still flagged: the binding is genuinely in
 scope there. Nested `try/catch` uses the nearest binding.
@@ -47,7 +41,7 @@ try { work(); } catch (err) { throw new Error('failed', { cause: err }); }
 try { work(); } catch (err) { throw err; }
 ```
 
-## Fix
+### Fix
 
 Autofix attaches `{ cause: <binding> }`:
 
@@ -58,9 +52,19 @@ Autofix attaches `{ cause: <binding> }`:
 A zero-argument `new SomeError()` is **reported but not autofixed** — inserting an options object as
 the first argument could clobber a positional message the rule cannot see.
 
-## Options
+## What it does not flag
 
-None.
+Deliberately conservative:
+
+- Only constructors whose simple name ends in `Error` or `Exception` are treated as errors
+  (`Error`, `TypeError`, `ValidationError`, `HttpException`). Throwing `new Response(...)` for
+  control flow is not policed.
+- Fires only when the enclosing catch binds a plain identifier (`catch (err)`). A parameterless
+  `catch {}` or a destructured binding (`catch ({ message })`) has no single name to attach, so the
+  throw is left alone.
+- Any `cause` property (whatever its value), and any spread the rule cannot see through, counts as
+  "has a cause" and suppresses the report — a hand-written cause is never second-guessed.
+- A bare re-throw of the caught error (`throw err`).
 
 ## When not to use it
 

package/docs/rules/require-registered-keys.md

@@ -2,6 +2,10 @@
 
 > The key/name argument of a configured sink API must be an imported constant, not a raw string.
 
+<!-- begin generated rule header -->
+⚙️ Opt-in: `off` in `recommended`; needs options (see Options) · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 String keys threaded into sink APIs — storage slots, event channels, feature flags, query-cache keys
@@ -26,9 +30,18 @@ localStorage.getItem(USER_PROFILE_KEY);
 emitter.on(TASK_DONE, handler);
 ```
 
+## What it does not flag
+
 Only string literals are flagged. An already-imported identifier, a template literal, or any computed
 expression is left alone — those are not the raw-string smell.
 
+`callee` is matched against the call's dotted identifier path (`localStorage.getItem`, `emitter.on`).
+A callee that is computed or not a plain identifier chain (`this.emitter.on`, `obj[k].on`, `a().b`)
+cannot be matched and is skipped.
+
+Calls to callees not listed in `sinks` (`sessionStorage.getItem` when only `localStorage.getItem` is
+configured) are not policed.
+
 ## Options
 
 | Option | Type | Default | Meaning |
@@ -51,10 +64,6 @@ key sinks to hard-code, so you declare which callees matter for your project.
 }]
 ```
 
-`callee` is matched against the call's dotted identifier path (`localStorage.getItem`, `emitter.on`).
-A callee that is computed or not a plain identifier chain (`this.emitter.on`, `obj[k].on`, `a().b`)
-cannot be matched and is skipped.
-
 ## When not to use it
 
 If your keys are already constants, or you have no registry module to import from, leave `sinks` empty

package/docs/rules/require-schema-parse-at-boundary.md

@@ -2,6 +2,10 @@
 
 > Parse external boundary data at runtime — don't assert its shape with `as T`.
 
+<!-- begin generated rule header -->
+Opt-in: `off` in `recommended` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 External data — a fetch body, a `JSON.parse` result, a message-event payload — has whatever shape the
@@ -17,7 +21,8 @@ const user = UserSchema.parse(await res.json()); // validated
 ## What it flags
 
 This is a **conservative syntactic slice** of a concept that is fully general only with type
-information. It flags a cast applied **directly** to a call site that is unmistakably a boundary read:
+information. It flags a cast whose target is a **shape claim** (a named type, an array, or a union
+containing one: `as User`, `as User[]`, `as User | null`) applied to a boundary read:
 
 ```ts bad reports=3
 const user = JSON.parse(raw) as User;
@@ -27,18 +32,107 @@ const fetched = (await res.json()) as User;
 
 ```ts good
 const user = UserSchema.parse(JSON.parse(raw));
+const users = UserSchema.array().parse(JSON.parse(raw));
 const fetched = UserSchema.parse(await res.json());
-const data = JSON.parse(raw) as unknown; // safe widening, not a shape claim
 ```
 
-Only these forms are flagged: `JSON.parse(...) as T` and `(await <expr>.json()) as T`, and only when
-the cast target is a shape claim (a named type or array — `as User`, `as User[]`). Casts to `unknown`,
-`any`, or `const` are the safe/neutral forms and are never flagged. A boundary value stored in a
-variable and cast later is out of syntactic reach — enforce that with a type-aware setup.
+The boundary reads it knows:
+
+| Source | Example |
+| --- | --- |
+| `JSON.parse(...)` | covers web storage and OpenAI `call.function.arguments` fed to it |
+| `await <expr>.json()` | a fetch `Response` body |
+| `localStorage.getItem` / `sessionStorage.getItem` | also through `window.` / `globalThis.` |
+| `URLSearchParams` `.get` / `.getAll` | `new URLSearchParams(...)`, `<x>.searchParams`, a `searchParams` binding, or a `const` bound to one of those |
+| `event.data` in a `message` listener | `x.addEventListener('message', fn)`, `x.onmessage = fn`, `onmessage = fn`, including a `{ data }` parameter |
+| Anthropic `tool_use` `.input` | `block.input` inside `if (block.type === 'tool_use')`, a `?:` / `&&` guard, `case 'tool_use':`, a `.find((b) => b.type === 'tool_use')` result, or a `.filter(...)` of that shape followed by `.map` / `.flatMap` / `.forEach` |
+| `boundaries` option | any callee you list |
+
+```ts bad reports=5
+const prefs = JSON.parse(localStorage.getItem('prefs') ?? '{}') as Prefs;
+const sort = new URLSearchParams(location.search).get('sort') as Sort;
+window.addEventListener('message', (event) => handle(event.data as Message));
+const args = JSON.parse(call.function.arguments) as WeatherArgs;
+if (block.type === 'tool_use') run(block.input as WeatherArgs);
+```
+
+```ts good
+const prefs = PrefsSchema.parse(JSON.parse(localStorage.getItem('prefs') ?? '{}'));
+const sort = SortSchema.parse(new URLSearchParams(location.search).get('sort'));
+window.addEventListener('message', (event) => handle(MessageSchema.parse(event.data)));
+const args = WeatherArgsSchema.parse(JSON.parse(call.function.arguments));
+if (block.type === 'tool_use') run(WeatherArgsSchema.parse(block.input));
+```
+
+### Through a `const`
+
+A boundary value stored in a `const` and cast later in the same function is flagged too:
+
+```ts bad
+async function loadUser(res: Response) {
+  const raw = await res.json();
+  return raw as User;
+}
+```
+
+```ts good
+async function loadUser(res: Response) {
+  const raw = await res.json();
+  return UserSchema.parse(raw);
+}
+```
+
+The binding is followed only when nothing could have checked the value first, so the rule gives the
+benefit of the doubt whenever it cannot prove otherwise:
+
+- Only a single `const name = <boundary>` is followed, never `let`, `var`, a destructuring pattern
+  or a parameter. Chains of such consts (`const body = await res.json(); const raw = body;`) are
+  followed.
+- The cast must be in the same function as the declaration.
+- Any read of the binding before the cast other than another `as` cast (a guard like
+  `isUser(raw)`, an `assertUser(raw)` call, an `'id' in raw` check, passing it to a function,
+  mutating a property) keeps the rule silent, as does any read from a nested function. Reads after
+  the cast do not excuse it.
+
+```ts prose reason="shows what the rule deliberately leaves alone, not a fix for an example above"
+async function loadUser(res: Response) {
+  const raw = await res.json();
+  assertUser(raw); // might have validated it: not flagged
+  return raw as User;
+}
+```
+
+## What it does not flag
+
+- Casts to `unknown`, `any`, `const` or a primitive keyword (`as string | null`): the safe or
+  neutral forms.
+- `satisfies`, which checks the value against the type instead of asserting it.
+- A cast of the parse result (`UserSchema.parse(raw) as User`): the schema already checked it.
+- Look-alikes that are not boundary reads: `cache.getItem(...)`, `map.get(...)`,
+  `headers.get(...)`, `.data` outside a `message` listener, `.input` without a `tool_use` guard.
+- A boundary value that is neither cast directly nor bound by a followed `const` (a property of
+  an object, a function return value). That needs a type-aware setup.
 
 ## Options
 
-None.
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `boundaries` | `string[]` | `[]` | Extra callees whose result is boundary data: a bare name or a dotted path. |
+
+```js
+'noctcore-contracts/require-schema-parse-at-boundary': ['error', {
+  // `readBody(event) as T` and `(await readBody(event)) as T` are then flagged.
+  boundaries: ['readBody', 'ipcRenderer.invoke'],
+}]
+```
+
+```ts bad options={"boundaries":["readBody"]}
+const body = (await readBody(event)) as Body;
+```
+
+```ts good
+const body = BodySchema.parse(await readBody(event));
+```
 
 ## When not to use it
 

package/docs/rules/restrict-throw-to-taxonomy.md

@@ -2,6 +2,10 @@
 
 > `throw` only members of your error taxonomy — never an ad hoc built-in nor a bare value.
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 A codebase that throws a curated set of error types can handle them exhaustively at the boundary:
@@ -15,10 +19,6 @@ breaks that: a non-Error carries no stack and no cause, and an unclassified erro
 - `throw new SomethingError(...)` whose constructor is **not** in the `allow` list.
 - `throw <non-Error value>` — a string, number, boolean, template literal, object, or array literal.
 
-Conservative on the ambiguous forms. A bare identifier (`throw err` — the re-throw), a member
-(`throw ctx.error`), and a call (`throw makeError()`) are all left alone: a syntactic rule cannot know
-whether they resolve to an Error, and re-throwing a caught error is the most common `throw` there is.
-
 ```ts bad reports=3
 // built-in not in the taxonomy
 throw new TypeError('bad');
@@ -34,6 +34,12 @@ throw new Error('boom');
 try { work(); } catch (err) { throw err; }
 ```
 
+## What it does not flag
+
+Conservative on the ambiguous forms. A bare identifier (`throw err` — the re-throw), a member
+(`throw ctx.error`), and a call (`throw makeError()`) are all left alone: a syntactic rule cannot know
+whether they resolve to an Error, and re-throwing a caught error is the most common `throw` there is.
+
 ## Options
 
 | Option | Type | Default | Meaning |

package/docs/rules/schema-enum-field-consistency.md

@@ -3,6 +3,10 @@
 > A field that is an enum in one zod object schema must not be `z.string()` in another schema of the
 > same module.
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 When schemas double as wire types (tRPC procedures, a shared contract package), the output schema is
@@ -50,6 +54,16 @@ export const ticketOutput = z.object({
 });
 ```
 
+## What it does not flag
+
+- `z.union([z.string(), z.null()])` and any `z.string()` chain with `.pipe()` or `.transform()`:
+  neither is a plain string.
+- A single `z.literal('X')`: a constant, not an enum.
+- An imported identifier, unless its name matches `enumIdentifierPattern` (see Options).
+- An enum in another file: the scope is one module.
+- Keys in `ignoreFields`, computed keys, and schemas built from a namespace not listed in
+  `zodIdentifiers`.
+
 ## Options
 
 | Option | Type | Default | Meaning |

package/docs/rules/translation-key-exists.md

@@ -2,6 +2,10 @@
 
 > Every static translation key must exist in the catalog of the namespace in scope.
 
+<!-- begin generated rule header -->
+⚙️ Opt-in: `off` in `recommended`; needs options (see Options) · 💭 Type information: used when available
+<!-- end generated rule header -->
+
 ## Why
 
 i18next does not fail on a missing key. It renders the key itself (`admin.portalAccounts.revokeTitle`)
@@ -56,7 +60,7 @@ Plural forms (`key_one`, `key_few`, `key_ordinal_other`) answer for `key` only w
 `count`, and context variants (`key_male`) only when it passes `context`, because without them
 i18next looks up the bare key and misses. A subtree or array answers only with `returnObjects`.
 
-### What it never reports
+## What it does not flag
 
 Anything it cannot resolve statically: a variable key (`t(someKey)`), a template key
 (`` t(`status.${s}`) ``), a key computed by a helper, a namespace held in an identifier it cannot
@@ -64,6 +68,15 @@ resolve (an import not listed in `namespaceIdentifiers`), an options bag it cann
 (`t('k', opts)`, `{ ...opts }`, `{ ns: someNs }`), and a `t` parameter with no `TFunction` type. The
 rule stays silent on those rather than guessing.
 
+### Dead keys are out of scope
+
+The reverse check, "a catalog key nothing uses", is not something a per-file ESLint rule can do
+soundly: it needs every source file at once, and ESLint may lint one file (editor), a subset
+(`--cache`, lint-staged), or shard files across workers. Worse, keys routinely flow as data
+(navigation tables, key-builder helpers, `` `errors:${code}` ``), which no call-site analysis
+sees. Run it as a whole-tree check instead, one that unions static keys, template-key prefixes
+and string literals that equal a key.
+
 ## Options
 
 | Option | Type | Default | Meaning |
@@ -140,15 +153,6 @@ found one real bug (`t('common.cancel')` in the default namespace, which renders
 namespace registered at runtime only inside a test (`registerFeatureNamespace('late-arrival', ...)`)
 is reported as unknown; exclude test files or add a catalog entry for it.
 
-## Dead keys are out of scope
-
-The reverse check, "a catalog key nothing uses", is not something a per-file ESLint rule can do
-soundly: it needs every source file at once, and ESLint may lint one file (editor), a subset
-(`--cache`, lint-staged), or shard files across workers. Worse, keys routinely flow as data
-(navigation tables, key-builder helpers, `` `errors:${code}` ``), which no call-site analysis
-sees. Run it as a whole-tree check instead, one that unions static keys, template-key prefixes
-and string literals that equal a key.
-
 ## When not to use it
 
 If your keys are mostly computed, or your catalogs are not JSON files on disk (fetched from a TMS at

package/docs/rules/wire-message-naming.md

@@ -2,6 +2,10 @@
 
 > A message-schema's `type` discriminant must be the kebab-case of its const name minus its role suffix. 🔧
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 🔧 Fixable with `--fix` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 When wire messages are modelled as zod objects with a `type: z.literal('…')` discriminant, the const
@@ -29,7 +33,11 @@ export const TaskCompletedEvent = z.object({ type: z.literal('task-completed') }
 export const RunTaskCommand = z.object({ type: z.literal('run-task') });
 ```
 
-Consts without a role suffix, and role-suffixed consts without a `type` literal, are ignored.
+## What it does not flag
+
+- Consts without a role suffix (`TaskSchema`), whatever their `type` literal says.
+- Role-suffixed consts without a `type: z.literal(...)` property.
+- Consts that are not exported: only `export const` declarations are checked.
 
 ## Options
 

package/docs/rules/zod-schema-naming.md

@@ -2,6 +2,10 @@
 
 > Every exported zod schema is a PascalCase const suffixed `Schema`, paired with a same-named inferred type.
 
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 A contracts package is a shared spine. A uniform `FooSchema` + `Foo` pairing keeps the schema and
@@ -30,6 +34,12 @@ export const TaskSchema = z.object({ id: z.string() });
 export type Task = z.infer<typeof TaskSchema>;
 ```
 
+## What it does not flag
+
+- Exported consts whose initializer is not rooted at `z` (`export const MAX = 10`).
+- Zod schemas that are not exported.
+- Consts ending in one of the configured `roleSuffixes` (see Options).
+
 ## Options
 
 | Option | Type | Default | Meaning |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-contracts",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "ESLint rules for shared contract, config, error-handling, and money-precision conventions (zod schema naming, wire discriminants, no-direct-process-env, decimal money).",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,7 @@
     "url": "git+https://github.com/noctcore/eslint-plugins.git",
     "directory": "packages/eslint-plugin-contracts"
   },
-  "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/eslint-plugin-contracts",
+  "homepage": "https://noctcore.github.io/eslint-plugins/packages/contracts/",
   "bugs": "https://github.com/noctcore/eslint-plugins/issues",
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
@@ -46,7 +46,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@noctcore/eslint-utils": "^0.1.1",
+    "@noctcore/eslint-utils": "^0.1.2",
     "@typescript-eslint/utils": "^8.61.1"
   },
   "peerDependencies": {
@@ -55,11 +55,11 @@
   },
   "devDependencies": {
     "@noctcore/eslint-test-utils": "workspace:*",
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/parser": "^8.61.1",
-    "@typescript-eslint/rule-tester": "^8.61.1",
+    "@types/node": "^22.20.3",
+    "@typescript-eslint/parser": "^8.70.0",
+    "@typescript-eslint/rule-tester": "^8.70.0",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "vitest": "^4"
+    "vitest": "^5"
   }
 }