@noctcore/eslint-plugin-contracts 0.2.0 → 0.4.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/docs/rules/translation-key-exists.md

@@ -0,0 +1,155 @@
+# `noctcore-contracts/translation-key-exists`
+
+> Every static translation key must exist in the catalog of the namespace in scope.
+
+## Why
+
+i18next does not fail on a missing key. It renders the key itself (`admin.portalAccounts.revokeTitle`)
+or silently falls back to another language, and nothing at build time says so. A renamed or deleted
+catalog key, a typo, or a key looked up in the wrong namespace is a UI regression that only a human
+reading the screen will catch. This rule resolves every static key the way i18next would and reports
+the ones that cannot resolve.
+
+## What it flags
+
+A static key that no configured catalog of the namespace in scope contains:
+
+```tsx
+// catalogs: common = { actions: { save, cancel } }, portal = { tasks: { title } }
+
+const { t } = useTranslation(); // default namespace: common
+t('actions.sav'); // ✗ typo
+t('common.cancel'); // ✗ the namespace is not a key segment; this renders "common.cancel"
+t('actions.save'); // ✓
+
+const { t: tp } = useTranslation('portal');
+tp('actions.save'); // ✗ exists, but in `common`, not `portal`
+tp('common:actions.save'); // ✓ explicit namespace
+tp('actions.save', { ns: 'common' }); // ✓ explicit namespace
+```
+
+It also reports a namespace that has no catalog at all (`useTranslation('portl')`), and a catalog
+that exists but cannot be parsed, once per file.
+
+### Where namespaces come from
+
+The rule reads them from syntax, per file, in the shapes i18next and react-i18next document:
+
+| Shape | Namespace(s) searched |
+| --- | --- |
+| `const { t } = useTranslation('ns')`, also `[t]`, `{ t: alias }`, `r.t` | `ns` |
+| `useTranslation(['a', 'b'])` | `a`, then `b` |
+| `useTranslation('ns', { keyPrefix: 'p' })` | `ns`, key prefixed with `p.` |
+| `const t = i18n.getFixedT(lng, 'ns', 'p')` | `ns`, key prefixed with `p.` |
+| `i18n.t(...)`, `i18next.t(...)`, an imported or global `t` | the default namespace |
+| `function f(t: TFunction<'ns'>)` | `ns` |
+| `t('ns:key')` | `ns` (wins over everything) |
+| `t('key', { ns: 'ns' })` | `ns` (wins over the binding) |
+| `<Trans i18nKey="key" ns="ns" t={t} />` | `ns`, else the bound `t`, else the default |
+
+A namespace argument may be a string literal, an array of literals, a same-file `const`, a name in
+`namespaceIdentifiers`, or, under typed linting, any identifier whose type is one string literal.
+
+### Plurals, context, objects
+
+Plural forms (`key_one`, `key_few`, `key_ordinal_other`) answer for `key` only when the call passes
+`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
+
+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
+resolve (an import not listed in `namespaceIdentifiers`), an options bag it cannot read
+(`t('k', opts)`, `{ ...opts }`, `{ ns: someNs }`), and a `t` parameter with no `TFunction` type. The
+rule stays silent on those rather than guessing.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `catalogs` | `{ file, namespace?, keyPath? }[]` | `[]` | Where each namespace's keys live. Empty = rule is inert. See below. |
+| `defaultNamespace` | `string` | `'translation'` | i18next `defaultNS`: what `useTranslation()` and `i18n.t` resolve to. |
+| `fallbackNamespaces` | `string[]` | `[]` | i18next `fallbackNS`: searched after the bound namespaces. |
+| `hooks` | `string[]` | `['useTranslation']` | Hooks returning a namespace-bound `t`. |
+| `instances` | `string[]` | `['i18n', 'i18next']` | i18next instances: `<instance>.t(...)`, `<instance>.getFixedT(...)`. |
+| `functions` | `string[]` | `['t']` | Bare translation functions bound to the default namespace when imported (by that name) or global. An untyped parameter with one of these names is skipped. |
+| `typeNames` | `string[]` | `['TFunction']` | Parameter types whose first type argument is the namespace, second the key prefix. |
+| `transComponents` | `string[]` | `['Trans']` | JSX components taking `i18nKey` / `ns` / `t` / `count` / `context` props. |
+| `namespaceIdentifiers` | `Record<string, string>` | `{}` | Imported identifiers that hold a namespace name, e.g. `{ HELP_NS: 'help' }`. |
+| `nsSeparator` | `string \| false` | `':'` | i18next `nsSeparator`. `false` turns off `ns:key` parsing. |
+| `keySeparator` | `string \| false` | `'.'` | i18next `keySeparator`. `false` means flat catalogs. |
+| `pluralSeparator` | `string` | `'_'` | i18next `pluralSeparator`. |
+| `contextSeparator` | `string` | `'_'` | i18next `contextSeparator`. |
+| `dynamicKeys` | `'ignore' \| 'check-prefix'` | `'ignore'` | `check-prefix` also requires a template key's static head (`` `status.${s}` `` → `status.`) to be the start of at least one key. Sound, since nothing else can match, but opt-in. |
+
+Relative paths resolve against the ESLint working directory. Match the separators and default
+namespace to your `i18next.init` options.
+
+### `catalogs`
+
+Each entry is a JSON file, or a subtree of one, holding a namespace's keys. Use the one reference
+language whose keys are the source of truth (catalog parity between languages is a different check).
+
+| Layout | Entry |
+| --- | --- |
+| one file per namespace | `{ file: 'public/locales/en/{ns}.json' }` |
+| one file, namespaces at the top level | `{ file: 'src/i18n/en.json', keyPath: '{ns}' }` |
+| a fixed file for one namespace | `{ file: 'src/i18n/common.en.json', namespace: 'common' }` |
+| single-namespace app | `{ file: 'src/i18n/en.json' }` (supplies `defaultNamespace`) |
+
+`{ns}` is replaced by the namespace being resolved, in `file` and in `keyPath` (a dot path). A
+templated entry whose file or subtree does not exist simply does not supply that namespace; a fixed
+entry that cannot be read is reported. Entries are unioned, so several may supply one namespace.
+Catalogs are read on demand, cached for the process, and re-read when their modification time
+changes. A namespace that would escape its directory (`..`, a path separator) is never substituted.
+
+### Worked example
+
+A Polish-first React app with two shared namespaces (`common`, `errors`) stored as the top-level
+keys of `apps/web/src/lib/i18n/locales/pl.json`, one namespace per feature at
+`apps/web/src/features/<ns>/locales/pl.json`, `defaultNS: 'common'`, and one namespace name
+exported as a constant from another module:
+
+```js
+import contracts from '@noctcore/eslint-plugin-contracts';
+
+export default [
+  {
+    files: ['apps/web/src/**/*.{ts,tsx}'],
+    plugins: { 'noctcore-contracts': contracts },
+    rules: {
+      'noctcore-contracts/translation-key-exists': [
+        'error',
+        {
+          catalogs: [
+            { file: 'apps/web/src/lib/i18n/locales/pl.json', keyPath: '{ns}' },
+            { file: 'apps/web/src/features/{ns}/locales/pl.json' },
+          ],
+          defaultNamespace: 'common',
+          namespaceIdentifiers: { HELP_NS: 'help' },
+        },
+      ],
+    },
+  },
+];
+```
+
+With that configuration the rule resolved 1,500 static keys across 1,110 files of that app and
+found one real bug (`t('common.cancel')` in the default namespace, which renders the raw key). A
+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
+runtime, generated at build time), leave this rule off.

package/package.json

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