@noctcore/eslint-plugin-contracts 0.5.0 → 0.6.1

package/dist/index.cjs

@@ -639,6 +639,7 @@ var DEFAULT_FIELD_PATTERNS = [
   "balance"
 ];
 var DEFAULT_ALLOWED_FILES = [];
+var DEFAULT_MINOR_UNIT_PATTERNS = [];
 var optionSchema3 = {
   type: "object",
   additionalProperties: false,
@@ -654,6 +655,11 @@ var optionSchema3 = {
       type: "array",
       items: { type: "string" },
       uniqueItems: true
+    },
+    minorUnitPatterns: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true
     }
   }
 };
@@ -692,7 +698,8 @@ var moneyMustBeDecimalRule = createRule({
     {
       decimalType: DEFAULT_DECIMAL_TYPE,
       fieldPatterns: [...DEFAULT_FIELD_PATTERNS],
-      allowedFiles: []
+      allowedFiles: [],
+      minorUnitPatterns: []
     }
   ],
   create(context, [options]) {
@@ -703,6 +710,11 @@ var moneyMustBeDecimalRule = createRule({
     }
     const fieldPatterns = options.fieldPatterns ?? DEFAULT_FIELD_PATTERNS;
     const moneyPattern = new RegExp(`(${fieldPatterns.join("|")})`, "i");
+    const minorUnitPatterns = options.minorUnitPatterns ?? DEFAULT_MINOR_UNIT_PATTERNS;
+    const minorUnitPattern = minorUnitPatterns.length > 0 ? new RegExp(`(${minorUnitPatterns.join("|")})`, "i") : null;
+    function isDecimalMoneyName(name) {
+      return moneyPattern.test(name) && !(minorUnitPattern?.test(name) ?? false);
+    }
     function report(node) {
       context.report({ node, messageId: "moneyMustBeDecimal", data: { decimalType } });
     }
@@ -713,7 +725,7 @@ var moneyMustBeDecimalRule = createRule({
           return;
         }
         const name = staticName(node.key);
-        if (name !== void 0 && moneyPattern.test(name) && isNumberAnnotation(node.typeAnnotation)) {
+        if (name !== void 0 && isDecimalMoneyName(name) && isNumberAnnotation(node.typeAnnotation)) {
           report(node);
         }
       },
@@ -723,7 +735,7 @@ var moneyMustBeDecimalRule = createRule({
           return;
         }
         const name = node.id.name;
-        if (moneyPattern.test(name) && isNumberAnnotation(node.id.typeAnnotation)) {
+        if (isDecimalMoneyName(name) && isNumberAnnotation(node.id.typeAnnotation)) {
           report(node);
         }
       }
@@ -2294,7 +2306,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-contracts";
-var VERSION = "0.3.0";
+var VERSION = "0.6.1";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-contracts", version: VERSION },
   rules,

package/dist/index.d.cts

@@ -51,6 +51,12 @@ interface MoneyMustBeDecimalOptions {
     readonly fieldPatterns?: readonly string[];
     /** Path-suffix allowlist of files to skip entirely. */
     readonly allowedFiles?: readonly string[];
+    /**
+     * Regex fragments (case-insensitive) naming fields that hold an integer count
+     * of minor units (cents), where `number` is the correct type. A money-named
+     * field matching one of these is not reported. Empty by default.
+     */
+    readonly minorUnitPatterns?: readonly string[];
 }
 
 interface NoDirectProcessEnvOptions {

package/dist/index.d.ts

@@ -51,6 +51,12 @@ interface MoneyMustBeDecimalOptions {
     readonly fieldPatterns?: readonly string[];
     /** Path-suffix allowlist of files to skip entirely. */
     readonly allowedFiles?: readonly string[];
+    /**
+     * Regex fragments (case-insensitive) naming fields that hold an integer count
+     * of minor units (cents), where `number` is the correct type. A money-named
+     * field matching one of these is not reported. Empty by default.
+     */
+    readonly minorUnitPatterns?: readonly string[];
 }
 
 interface NoDirectProcessEnvOptions {

package/dist/index.js

@@ -595,6 +595,7 @@ var DEFAULT_FIELD_PATTERNS = [
   "balance"
 ];
 var DEFAULT_ALLOWED_FILES = [];
+var DEFAULT_MINOR_UNIT_PATTERNS = [];
 var optionSchema3 = {
   type: "object",
   additionalProperties: false,
@@ -610,6 +611,11 @@ var optionSchema3 = {
       type: "array",
       items: { type: "string" },
       uniqueItems: true
+    },
+    minorUnitPatterns: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true
     }
   }
 };
@@ -648,7 +654,8 @@ var moneyMustBeDecimalRule = createRule({
     {
       decimalType: DEFAULT_DECIMAL_TYPE,
       fieldPatterns: [...DEFAULT_FIELD_PATTERNS],
-      allowedFiles: []
+      allowedFiles: [],
+      minorUnitPatterns: []
     }
   ],
   create(context, [options]) {
@@ -659,6 +666,11 @@ var moneyMustBeDecimalRule = createRule({
     }
     const fieldPatterns = options.fieldPatterns ?? DEFAULT_FIELD_PATTERNS;
     const moneyPattern = new RegExp(`(${fieldPatterns.join("|")})`, "i");
+    const minorUnitPatterns = options.minorUnitPatterns ?? DEFAULT_MINOR_UNIT_PATTERNS;
+    const minorUnitPattern = minorUnitPatterns.length > 0 ? new RegExp(`(${minorUnitPatterns.join("|")})`, "i") : null;
+    function isDecimalMoneyName(name) {
+      return moneyPattern.test(name) && !(minorUnitPattern?.test(name) ?? false);
+    }
     function report(node) {
       context.report({ node, messageId: "moneyMustBeDecimal", data: { decimalType } });
     }
@@ -669,7 +681,7 @@ var moneyMustBeDecimalRule = createRule({
           return;
         }
         const name = staticName(node.key);
-        if (name !== void 0 && moneyPattern.test(name) && isNumberAnnotation(node.typeAnnotation)) {
+        if (name !== void 0 && isDecimalMoneyName(name) && isNumberAnnotation(node.typeAnnotation)) {
           report(node);
         }
       },
@@ -679,7 +691,7 @@ var moneyMustBeDecimalRule = createRule({
           return;
         }
         const name = node.id.name;
-        if (moneyPattern.test(name) && isNumberAnnotation(node.id.typeAnnotation)) {
+        if (isDecimalMoneyName(name) && isNumberAnnotation(node.id.typeAnnotation)) {
           report(node);
         }
       }
@@ -2250,7 +2262,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-contracts";
-var VERSION = "0.3.0";
+var VERSION = "0.6.1";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-contracts", version: VERSION },
   rules,

package/docs/rules/env-var-schema-parity.md

@@ -15,7 +15,7 @@ declaration in lockstep.
 A static `process.env.FOO` or `import.meta.env.FOO` access whose key `FOO` is not declared in the
 configured schema file:
 
-```ts
+```ts prose reason="the rule reads the schema file named in its options from disk"
 // schema (.env.example) declares DATABASE_URL, PORT, NODE_ENV
 
 // ✗

package/docs/rules/fetch-must-check-ok.md

@@ -15,27 +15,37 @@ status the server actually sent. Check the response first, and the failure is na
 
 A `.json()` read on a response bound from a configured fetch callee when no check governs it.
 
-```ts
-// ✗ no check at all
+```ts bad reports=4
+// no check at all
 export async function loadUser(id: string) {
   const res = await fetch(`/api/users/${id}`);
   return res.json();
 }
 
-// ✗ the check comes after the body is already parsed
-const data = await res.json();
-if (!res.ok) throw new Error('failed');
+// the check comes after the body is already parsed
+export async function loadOrder(id: string) {
+  const res = await fetch(`/api/orders/${id}`);
+  const data = await res.json();
+  if (!res.ok) throw new Error('failed');
+  return data;
+}
 
-// ✗ a single-code guard lets every other error through
-if (res.status === 404) return null;
-return res.json();
+// a single-code guard lets every other error through
+export async function findUser(id: string) {
+  const res = await fetch(`/api/users/${id}`);
+  if (res.status === 404) return null;
+  return res.json();
+}
 
-// ✗ `||` runs the parse exactly on the failure path
-return res.ok || res.json();
+// `||` runs the parse exactly on the failure path
+export async function loadFlags() {
+  const res = await fetch('/api/flags');
+  return res.ok || res.json();
+}
 ```
 
-```ts
-// ✓ guard clause
+```ts good
+// guard clause
 export async function loadUser(id: string) {
   const res = await fetch(`/api/users/${id}`);
   if (!res.ok) {
@@ -44,16 +54,30 @@ export async function loadUser(id: string) {
   return res.json();
 }
 
-// ✓ the parse sits in the branch the check permits
-return res.ok ? res.json() : null;
+// the parse sits in the branch the check permits
+export async function findUser(id: string) {
+  const res = await fetch(`/api/users/${id}`);
+  return res.ok ? res.json() : null;
+}
 
-// ✓ a status split at the success/error boundary, or a switch on success codes
-if (res.status >= 400) return null;
-switch (res.status) { case 200: case 201: return res.json(); default: return null; }
+// a status split at the success/error boundary, or a switch on success codes
+export async function loadOrder(id: string) {
+  const res = await fetch(`/api/orders/${id}`);
+  if (res.status >= 400) return null;
+  return res.json();
+}
+
+export async function createOrder() {
+  const res = await fetch('/api/orders', { method: 'POST' });
+  switch (res.status) { case 200: case 201: return res.json(); default: return null; }
+}
 
-// ✓ an assertion helper (`assert`, `invariant`, `ensure*`, `expect*`)
-invariant(res.ok, 'user request failed');
-return res.json();
+// an assertion helper (`assert`, `invariant`, `ensure*`, `expect*`)
+export async function loadFlags() {
+  const res = await fetch('/api/flags');
+  invariant(res.ok, 'user request failed');
+  return res.json();
+}
 ```
 
 Three response shapes are tracked: `const res = await fetch(...)` then `res.json()` in the same block,

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

@@ -20,12 +20,12 @@ Conservative on purpose. Untyped declarations and numeric-literal initializers (
 **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
-// ✗
+```ts bad reports=2
 class Invoice { total: number; }
 const amount: number = 5;
+```
 
-// ✓
+```ts good
 class Invoice { total: Decimal; }
 const count: number = 3;          // not a money name
 interface Payment { amount: number; }   // type member, out of scope
@@ -38,6 +38,7 @@ interface Payment { amount: number; }   // type member, out of scope
 | `decimalType` | `string` | `'Decimal'` | Name of the money type to require; appears in the report message. |
 | `fieldPatterns` | `string[]` | `['amount', 'price', 'cost', 'total', 'balance']` | Case-insensitive regex fragments identifying money-named fields (OR-combined). |
 | `allowedFiles` | `string[]` | `[]` | Path-suffix allowlist of files skipped entirely (e.g. `apps/api/src/legacy/totals.ts`). |
+| `minorUnitPatterns` | `string[]` | `[]` | Case-insensitive regex fragments naming fields that hold integer minor units on purpose and are therefore not reported. Checked before `fieldPatterns`. |
 
 ```js
 'noctcore-contracts/money-must-be-decimal': ['error', {
@@ -46,7 +47,26 @@ interface Payment { amount: number; }   // type member, out of scope
 }]
 ```
 
+## 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
+fields, which is how a project ends up turning the rule off entirely and losing it everywhere
+else.
+
+Name the boundary fields instead, so the rule keeps policing the rest of the codebase:
+
+```json
+{ "minorUnitPatterns": ["amountInCents", "unitAmount", "^amount$"] }
+```
+
+Prefer patterns that are specific to the boundary. A blanket `amount` would exempt every field
+whose name contains it, including the internal totals this rule exists to protect.
+
 ## When not to use it
 
-If your project does not have a dedicated Decimal money type, or represents money as integer minor
-units (cents) typed `number` on purpose, this rule does not fit.
+If your project has no dedicated Decimal money type, this rule does not fit.
+
+If it represents money as integer minor units **everywhere**, by choice, the rule can still be
+useful with `minorUnitPatterns` covering that convention, but at that point it is asserting a
+naming convention rather than a type, and you may not want it.

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

@@ -15,19 +15,25 @@ Any `process.env` access, in every position — property read (`process.env.X`),
 (`process.env[X]`), destructure (`const { X } = process.env`), or the bare value passed / returned /
 assigned (`log(process.env)`, `return process.env`). Computed `process['env']` cannot bypass it.
 
-```ts
-// ✗
+```ts bad reports=3
 const isProd = process.env.NODE_ENV === 'production';
 const { DATABASE_URL } = process.env;
 const env = process['env'];
+```
+
+```ts good
+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.
 
+```ts good filename=vite.config.ts relocation
+const isProd = process.env.NODE_ENV === 'production';
+```
+
 ## Options
 
 | Option | Type | Default | Meaning |

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

@@ -9,7 +9,7 @@ discarding `error.cause`, the stack, and any custom fields. The value that reach
 sentence with no chain to the underlying failure. The guarded extractor idiom preserves the object for
 structured loggers and stays legal:
 
-```ts
+```ts good
 error instanceof Error ? error.message : String(error)
 ```
 
@@ -18,14 +18,15 @@ error instanceof Error ? error.message : String(error)
 Only the three unambiguous cause-chain-dropping forms, and only when the operand is a known error
 identifier (default `error`, `err`, `e`, `cause`):
 
-```ts
-// ✗
+```ts bad reports=4
 logger.error(`request failed: ${error}`);
-const msg = err.toString();
-const msg = error + "";
-const msg = "" + e;
+const a = err.toString();
+const b = error + "";
+const c = "" + e;
+```
 
-// ✓  the guarded idiom (bare String(error) is intentionally NOT policed)
+```ts good
+// the guarded idiom (bare String(error) is intentionally NOT policed)
 const msg = error instanceof Error ? error.message : String(error);
 const m = `${error.message}`;
 ```

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

@@ -9,7 +9,7 @@ forward the caught error as `cause`, the underlying failure — its message, sta
 cause — is gone. The stack you see points only at the re-throw site. `Error`'s standard `cause`
 option (and every `*Error` subclass that forwards it) preserves the chain:
 
-```ts
+```ts good
 try {
   await db.query(sql);
 } catch (err) {
@@ -34,14 +34,15 @@ Deliberately conservative:
 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.
 
-```ts
-// ✗  drops the cause  →  autofixes to `new Error('failed', { cause: err })`
+```ts bad reports=2
+// drops the cause: autofixes to `new Error('failed', { cause: err })`
 try { work(); } catch (err) { throw new Error('failed'); }
 
-// ✗  merges into an existing options object
+// merges into an existing options object
 try { work(); } catch (err) { throw new HttpError('failed', { status: 500 }); }
+```
 
-// ✓
+```ts good
 try { work(); } catch (err) { throw new Error('failed', { cause: err }); }
 try { work(); } catch (err) { throw err; }
 ```

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

@@ -14,14 +14,13 @@ compile error instead of a runtime miss.
 
 A **raw string literal** in the configured key position of a configured sink call:
 
-```ts
-// with sinks: [{ callee: 'localStorage.getItem', argIndex: 0 }, { callee: 'emitter.on', argIndex: 0 }]
-
-// ✗
+```ts bad reports=2 options={"sinks":[{"callee":"localStorage.getItem","argIndex":0},{"callee":"emitter.on","argIndex":0}]}
 localStorage.getItem('user-profile');
 emitter.on('task-done', handler);
+```
 
-// ✓  imported constant
+```ts good options={"sinks":[{"callee":"localStorage.getItem","argIndex":0},{"callee":"emitter.on","argIndex":0}]}
+// imported constant
 import { USER_PROFILE_KEY, TASK_DONE } from '@/keys';
 localStorage.getItem(USER_PROFILE_KEY);
 emitter.on(TASK_DONE, handler);

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

@@ -10,7 +10,7 @@ promise the runtime never checks: a field the server dropped is now `undefined`
 `string`, and the corruption surfaces far from the boundary. Parsing with a runtime schema
 (zod/valibot) validates the shape at the edge and fails loudly there:
 
-```ts
+```ts good
 const user = UserSchema.parse(await res.json()); // validated
 ```
 
@@ -19,15 +19,15 @@ const user = UserSchema.parse(await res.json()); // validated
 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:
 
-```ts
-// ✗
+```ts bad reports=3
 const user = JSON.parse(raw) as User;
 const users = JSON.parse(raw) as User[];
-const user = (await res.json()) as User;
+const fetched = (await res.json()) as User;
+```
 
-// ✓
+```ts good
 const user = UserSchema.parse(JSON.parse(raw));
-const user = UserSchema.parse(await res.json());
+const fetched = UserSchema.parse(await res.json());
 const data = JSON.parse(raw) as unknown; // safe widening, not a shape claim
 ```
 

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

@@ -19,15 +19,17 @@ Conservative on the ambiguous forms. A bare identifier (`throw err` — the re-t
 (`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
-// ✗  built-in not in the taxonomy
+```ts bad reports=3
+// built-in not in the taxonomy
 throw new TypeError('bad');
 
-// ✗  bare values
+// bare values
 throw 'boom';
 throw { code: 500 };
+```
 
-// ✓  (default allow is ['Error'])
+```ts good
+// default allow is ['Error']
 throw new Error('boom');
 try { work(); } catch (err) { throw err; }
 ```

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

@@ -26,8 +26,8 @@ Per file, purely syntactic, no type information. The rule collects every propert
 Every **string** occurrence of a key that is **enum** elsewhere in the file is reported. No autofix:
 the right fix may be a data migration (the stored column was free text), not a schema edit.
 
-```ts
-// ✗ the output widens what both inputs narrow
+```ts bad reports=1
+// the output widens what both inputs narrow
 export const statusSchema = z.enum(['OPEN', 'CLOSED']);
 
 export const ticketCreateInput = z.object({ status: statusSchema.default('OPEN') });
@@ -38,8 +38,12 @@ export const ticketOutput = z.object({
 });
 ```
 
-```ts
-// ✓ the output reuses the enum
+```ts good
+// the output reuses the enum
+export const statusSchema = z.enum(['OPEN', 'CLOSED']);
+
+export const ticketCreateInput = z.object({ status: statusSchema.default('OPEN') });
+export const ticketUpdateInput = z.object({ status: statusSchema.optional() });
 export const ticketOutput = z.object({
   id: z.string(),
   status: statusSchema.nullable(),

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

@@ -14,7 +14,7 @@ the ones that cannot resolve.
 
 A static key that no configured catalog of the namespace in scope contains:
 
-```tsx
+```tsx prose reason="the rule reads the translation catalogs named in its options from disk"
 // catalogs: common = { actions: { save, cancel } }, portal = { tasks: { title } }
 
 const { t } = useTranslation(); // default namespace: common

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

@@ -16,15 +16,17 @@ whose zod object declares a `type: z.literal('…')` property, the literal must
 `kebab(constName minus the role suffix)`. A mismatch is reported and **autofixed** to the expected
 value.
 
-```ts
-// ✗ camelCase discriminant  →  autofixes to 'task-completed'
+```ts bad reports=2
+// camelCase discriminant: autofixes to 'task-completed'
 export const TaskCompletedEvent = z.object({ type: z.literal('taskCompleted') });
 
-// ✗ wrong value              →  autofixes to 'run-task'
+// wrong value: autofixes to 'run-task'
 export const RunTaskCommand = z.object({ type: z.literal('run') });
+```
 
-// ✓
+```ts good
 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.
@@ -39,8 +41,8 @@ Consts without a role suffix, and role-suffixed consts without a `type` literal,
 'noctcore-contracts/wire-message-naming': ['error', { roleSuffixes: ['Message'] }]
 ```
 
-```ts
-// with roleSuffixes: ['Message']  →  autofixes to 'task-done'
+```ts bad options={"roleSuffixes":["Message"]}
+// with roleSuffixes: ['Message'], autofixes to 'task-done'
 export const TaskDoneMessage = z.object({ type: z.literal('done') });
 ```
 

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

@@ -17,14 +17,15 @@ For every `export const` whose initializer is rooted at the `z` identifier (`z.o
 - a correctly-named `FooSchema` must have a sibling `export type Foo` (a `type` alias or
   `interface`) — otherwise `missingType`.
 
-```ts
-// ✗ not suffixed `Schema`
+```ts bad reports=2
+// not suffixed `Schema`
 export const Task = z.object({});
 
-// ✗ no sibling inferred type
+// no sibling inferred type
 export const TaskSchema = z.object({});
+```
 
-// ✓
+```ts good
 export const TaskSchema = z.object({ id: z.string() });
 export type Task = z.infer<typeof TaskSchema>;
 ```
@@ -43,7 +44,7 @@ suffixes to carve them out:
 'noctcore-contracts/zod-schema-naming': ['error', { roleSuffixes: ['Event', 'Command', 'Query'] }]
 ```
 
-```ts
+```ts good options={"roleSuffixes":["Event","Command","Query"]} reconfigured
 // carved out only when 'Command' is listed in roleSuffixes
 export const RunTaskCommand = z.object({ type: z.literal('run-task') });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-contracts",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -46,7 +46,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@noctcore/eslint-utils": "^0.1.0",
+    "@noctcore/eslint-utils": "^0.1.1",
     "@typescript-eslint/utils": "^8.61.1"
   },
   "peerDependencies": {