@noctcore/eslint-plugin-contracts 0.1.0 → 0.2.0

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

@@ -0,0 +1,54 @@
+# `noctcore-contracts/env-var-schema-parity`
+
+> Every `process.env.FOO` / `import.meta.env.FOO` key must be declared in a schema file.
+
+## Why
+
+An env var that is read in code but declared nowhere is config drift waiting to fail in production:
+nothing documents it, nothing validates it, and nothing provisions it in a fresh environment. A typo
+(`process.env.DATABSE_URL`) reads `undefined` and fails deep in a request. Cross-checking every access
+against a single schema file — a `.env.example` or a zod-env module — keeps config access and config
+declaration in lockstep.
+
+## What it flags
+
+A static `process.env.FOO` or `import.meta.env.FOO` access whose key `FOO` is not declared in the
+configured schema file:
+
+```ts
+// schema (.env.example) declares DATABASE_URL, PORT, NODE_ENV
+
+// ✗
+const secret = process.env.MISSING_KEY;
+const flag = import.meta.env.ALSO_MISSING;
+
+// ✓
+const url = process.env.DATABASE_URL;
+const port = import.meta.env.PORT;
+```
+
+Only static accesses are policed. Computed (`process.env[dynamic]`) and destructured reads are left
+alone.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `schema` | `string` | — | Path to the env declaration source (`.env.example` or a zod-env module). Relative paths resolve against the ESLint working directory. |
+
+**Inert until configured.** With no `schema` the rule reports nothing. The schema is read once per
+resolved path and cached for the process. The parser is format-agnostic and permissive: it unions
+dotenv keys (`FOO=...`) with object-property keys (`FOO: z.string()`, `'FOO': ...`), so it accepts
+both a `.env.example` and a zod-env module — and over-collection only ever suppresses a report, never
+invents one. If the schema cannot be read, the rule goes inert rather than flagging every access.
+
+```js
+'noctcore-contracts/env-var-schema-parity': ['error', { schema: '.env.example' }]
+// or a zod-env module:
+'noctcore-contracts/env-var-schema-parity': ['error', { schema: 'src/env.ts' }]
+```
+
+## When not to use it
+
+If you have no single schema of record for env vars, or read env dynamically by design, leave this
+rule off (or unset `schema` to keep it inert).

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

@@ -0,0 +1,67 @@
+# `noctcore-contracts/require-error-cause`
+
+> Re-throwing inside a `catch` without `{ cause }` severs the chain to the original error. 🔧
+
+## Why
+
+When you catch an error and throw a new one, the new error is what reaches your logger. If you do not
+forward the caught error as `cause`, the underlying failure — its message, stack, and any nested
+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
+try {
+  await db.query(sql);
+} catch (err) {
+  throw new QueryError('load failed', { cause: err }); // chain intact
+}
+```
+
+## 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.
+
+```ts
+// ✗  drops the cause  →  autofixes to `new Error('failed', { cause: err })`
+try { work(); } catch (err) { throw new Error('failed'); }
+
+// ✗  merges into an existing options object
+try { work(); } catch (err) { throw new HttpError('failed', { status: 500 }); }
+
+// ✓
+try { work(); } catch (err) { throw new Error('failed', { cause: err }); }
+try { work(); } catch (err) { throw err; }
+```
+
+## Fix
+
+Autofix attaches `{ cause: <binding> }`:
+
+- one argument (`new Error('msg')`) → appends a new options object;
+- an existing options object → merges `cause` in;
+- an empty options object (`{}`) → fills it.
+
+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
+
+None.
+
+## When not to use it
+
+If your error classes do not accept an options object with `cause` (pre-ES2022 targets without a
+polyfill), or you deliberately model errors without chaining, leave this rule off.

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

@@ -0,0 +1,62 @@
+# `noctcore-contracts/require-registered-keys`
+
+> The key/name argument of a configured sink API must be an imported constant, not a raw string.
+
+## Why
+
+String keys threaded into sink APIs — storage slots, event channels, feature flags, query-cache keys
+— are a classic drift hazard. One call spells the key `'user-profile'`, another `'userProfile'`, and
+the two silently never meet: a write lands in one slot, a read misses it. Funnelling every key through
+an imported constant from a single registry module makes the key a shared fact, and a typo becomes a
+compile error instead of a runtime miss.
+
+## What it flags
+
+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 }]
+
+// ✗
+localStorage.getItem('user-profile');
+emitter.on('task-done', handler);
+
+// ✓  imported constant
+import { USER_PROFILE_KEY, TASK_DONE } from '@/keys';
+localStorage.getItem(USER_PROFILE_KEY);
+emitter.on(TASK_DONE, handler);
+```
+
+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.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `sinks` | `{ callee: string, argIndex: number }[]` | `[]` | Callees (dotted paths) and the zero-based argument index to police. |
+| `registry` | `string` | — | Optional module the constants should be imported from; named in the report. |
+
+**Inert until configured.** With `sinks` empty the rule reports nothing — there is no universal set of
+key sinks to hard-code, so you declare which callees matter for your project.
+
+```js
+'noctcore-contracts/require-registered-keys': ['error', {
+  sinks: [
+    { callee: 'localStorage.getItem', argIndex: 0 },
+    { callee: 'localStorage.setItem', argIndex: 0 },
+    { callee: 'emitter.on', argIndex: 0 },
+    { callee: 'queryClient.getQueryData', argIndex: 0 },
+  ],
+  registry: '@/keys',
+}]
+```
+
+`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
+(the rule stays inert) or the rule off.

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

@@ -0,0 +1,47 @@
+# `noctcore-contracts/require-schema-parse-at-boundary`
+
+> Parse external boundary data at runtime — don't assert its shape with `as T`.
+
+## Why
+
+External data — a fetch body, a `JSON.parse` result, a message-event payload — has whatever shape the
+sender actually sent, which TypeScript never sees. Asserting it with `as User` is a compile-time
+promise the runtime never checks: a field the server dropped is now `undefined` masquerading as a
+`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
+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:
+
+```ts
+// ✗
+const user = JSON.parse(raw) as User;
+const users = JSON.parse(raw) as User[];
+const user = (await res.json()) as User;
+
+// ✓
+const user = UserSchema.parse(JSON.parse(raw));
+const user = 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.
+
+## Options
+
+None.
+
+## When not to use it
+
+If you deliberately trust certain boundaries (an internal service with a shared type package) or have
+a type-aware lint pass that supersedes this heuristic, leave this rule off. It ships `off` in the
+`recommended` preset for that reason — enable it where the boundary is genuinely untrusted.

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

@@ -0,0 +1,54 @@
+# `noctcore-contracts/restrict-throw-to-taxonomy`
+
+> `throw` only members of your error taxonomy — never an ad hoc built-in nor a bare value.
+
+## Why
+
+A codebase that throws a curated set of error types can handle them exhaustively at the boundary:
+one place maps `AppError` → HTTP status, `ValidationError` → 422, and so on. Throwing an arbitrary
+built-in (`TypeError`, `RangeError`) or, worse, a bare value (`throw 'nope'`, `throw { code }`)
+breaks that: a non-Error carries no stack and no cause, and an unclassified error falls through every
+`instanceof` branch.
+
+## What it flags
+
+- `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
+// ✗  built-in not in the taxonomy
+throw new TypeError('bad');
+
+// ✗  bare values
+throw 'boom';
+throw { code: 500 };
+
+// ✓  (default allow is ['Error'])
+throw new Error('boom');
+try { work(); } catch (err) { throw err; }
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `allow` | `string[]` | `['Error']` | Constructor names permitted as throw targets. Extend it with your base errors **and** any built-ins you legitimately raise. |
+
+```js
+'noctcore-contracts/restrict-throw-to-taxonomy': ['error', {
+  allow: ['AppError', 'ValidationError', 'NotFoundError', 'TypeError'],
+}]
+```
+
+The default `['Error']` is intentionally strict — it assumes a taxonomy rooted at `Error` and treats
+every other built-in as something you should opt into. Widen `allow` to match your project's error
+model on day one.
+
+## When not to use it
+
+If you have no error taxonomy yet, or intentionally throw built-ins throughout, leave this rule off
+until you have a base error class worth enforcing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-contracts",
-  "version": "0.1.0",
+  "version": "0.2.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",