@noctcore/eslint-plugin-contracts 0.2.0 → 0.3.0

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

@@ -0,0 +1,83 @@
+# `noctcore-contracts/fetch-must-check-ok`
+
+> A fetch response must be checked with `.ok` or a status comparison before `.json()` parses its body.
+
+Ported from tsforge's `typescript-core/fetch-must-check-ok` (MIT).
+
+## Why
+
+`fetch` rejects only on a network failure. A 4xx or 5xx resolves normally, and `.json()` then parses
+the error body as if it were data. Wrapping the call in `try` does not help on its own: the code
+fails closed, but every bad response surfaces as a parse or schema error that says nothing about the
+status the server actually sent. Check the response first, and the failure is named where it happens.
+
+## What it flags
+
+A `.json()` read on a response bound from a configured fetch callee when no check governs it.
+
+```ts
+// ✗ 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');
+
+// ✗ a single-code guard lets every other error through
+if (res.status === 404) return null;
+return res.json();
+
+// ✗ `||` runs the parse exactly on the failure path
+return res.ok || res.json();
+```
+
+```ts
+// ✓ guard clause
+export async function loadUser(id: string) {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) {
+    throw new Error(`user request failed: ${res.status}`);
+  }
+  return res.json();
+}
+
+// ✓ the parse sits in the branch the check permits
+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; }
+
+// ✓ an assertion helper (`assert`, `invariant`, `ensure*`, `expect*`)
+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,
+`fetch(...).then((res) => ...)`, and the unbound `(await fetch(...)).json()`, which is always reported.
+Aliases work (`const ok = res.ok; if (!ok) throw ...`). A bare `if (res.status)` or
+`typeof res.status === 'number'` is not a check: both are true for a 500.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `fetchFunctions` | `string[]` | `['fetch']` | Callees that return a `Response`: a bare name or a dotted path. |
+
+List every name you want tracked, including `fetch` itself:
+
+```js
+'noctcore-contracts/fetch-must-check-ok': ['error', {
+  fetchFunctions: ['fetch', 'globalThis.fetch', 'fetchWithRetry'],
+}]
+```
+
+## Limits
+
+Purely syntactic, no type information. A response assigned later (`let res; res = await fetch(...)`),
+passed to another function, or returned from a wrapper that is not in `fetchFunctions` is not tracked.
+A nested function that reuses the response's name is treated as the same binding. Clients whose
+`.json()` already throws on a bad status (ky, for example) do not belong in `fetchFunctions`.

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

@@ -0,0 +1,75 @@
+# `noctcore-contracts/schema-enum-field-consistency`
+
+> A field that is an enum in one zod object schema must not be `z.string()` in another schema of the
+> same module.
+
+## Why
+
+When schemas double as wire types (tRPC procedures, a shared contract package), the output schema is
+the type the client imports. If a field is an enum on the inputs but `z.string()` on the output, the
+widened type leaks `string` to every consumer, which then narrows or casts by hand. Each schema is
+correct on its own, so neither the compiler nor review catches it.
+
+## What it flags
+
+Per file, purely syntactic, no type information. The rule collects every property of every
+`z.object` / `z.strictObject` / `z.looseObject` and every `.extend` / `.safeExtend` shape, unwraps
+`.optional()`, `.nullable()`, `.nullish()`, `.default()`, `.prefault()`, `.catch()`, `.describe()`,
+`.meta()` and `.readonly()`, and classifies each value:
+
+- **enum**: `z.enum(...)`, `z.nativeEnum(...)`, a `z.union` of only `z.literal`s, a multi-value
+  `z.literal([...])`, `.extract()` / `.exclude()` of an enum, or an identifier whose same-file
+  declaration is one of those (or an import matching `enumIdentifierPattern`)
+- **string**: a chain rooted at `z.string()` with no `.pipe()` or `.transform()`
+- anything else is ignored, including `z.union([z.string(), z.null()])`
+
+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
+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: z.string().nullable(),
+});
+```
+
+```ts
+// ✓ the output reuses the enum
+export const ticketOutput = z.object({
+  id: z.string(),
+  status: statusSchema.nullable(),
+});
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `zodIdentifiers` | `string[]` | `['z']` | Names zod is imported under. |
+| `ignoreFields` | `string[]` | `[]` | Keys that genuinely mean different things in two schemas. |
+| `enumIdentifierPattern` | `string` (regex source) | unset | An imported identifier counts as an enum only when its name matches. |
+
+Imported identifiers are **not** assumed to be enums by default, so `email: emailSchema` (a string
+schema from another module) is not flagged against `email: z.string()`. If your project names its
+enum schemas consistently, opt them in:
+
+```js
+'noctcore-contracts/schema-enum-field-consistency': ['error', {
+  zodIdentifiers: ['z'],
+  enumIdentifierPattern: '(Status|Kind|Role)Schema$',
+  ignoreFields: ['type'],
+}]
+```
+
+Scope the rule to your schema modules with the config block's `files` (for example
+`files: ['src/schemas/**/*.ts']`); the rule itself assumes no layout.
+
+## When not to use it
+
+If a module intentionally keeps free-text and enum variants of the same key (a legacy import format
+beside the validated one), list that key in `ignoreFields` rather than turning the rule off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-contracts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -60,6 +60,6 @@
     "@typescript-eslint/rule-tester": "^8.61.1",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "vitest": "^3"
+    "vitest": "^4"
   }
 }