@noctcore/eslint-plugin-contracts 0.1.0

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

@@ -0,0 +1,47 @@
+# `noctcore-contracts/no-error-stringify`
+
+> Stringifying an error with `${error}`, `error.toString()`, or `error + ""` drops its cause chain.
+
+## Why
+
+`` `${error}` ``, `error.toString()`, and `error + ""` all coerce an `Error` to its `message` alone,
+discarding `error.cause`, the stack, and any custom fields. The value that reaches your logs is a bare
+sentence with no chain to the underlying failure. The guarded extractor idiom preserves the object for
+structured loggers and stays legal:
+
+```ts
+error instanceof Error ? error.message : String(error)
+```
+
+## What it flags
+
+Only the three unambiguous cause-chain-dropping forms, and only when the operand is a known error
+identifier (default `error`, `err`, `e`, `cause`):
+
+```ts
+// ✗
+logger.error(`request failed: ${error}`);
+const msg = err.toString();
+const msg = error + "";
+const msg = "" + e;
+
+// ✓  the guarded idiom (bare String(error) is intentionally NOT policed)
+const msg = error instanceof Error ? error.message : String(error);
+const m = `${error.message}`;
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `errorIdentifierNames` | `string[]` | `['error', 'err', 'e', 'cause']` | Identifier names treated as errors for the three flagged forms. |
+
+```js
+'noctcore-contracts/no-error-stringify': ['error', { errorIdentifierNames: ['error', 'cause', 'failure'] }]
+```
+
+## When not to use it
+
+If your codebase deliberately renders errors to strings at the boundary (and has already extracted the
+cause), or names error bindings unpredictably, this rule may be noisy — narrow or widen
+`errorIdentifierNames` to fit.

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

@@ -0,0 +1,51 @@
+# `noctcore-contracts/wire-message-naming`
+
+> A message-schema's `type` discriminant must be the kebab-case of its const name minus its role suffix. 🔧
+
+## Why
+
+When wire messages are modelled as zod objects with a `type: z.literal('…')` discriminant, the const
+name and the on-the-wire discriminant are two spellings of the same fact. Deriving one from the other
+by convention (`TaskCompletedEvent` ⇒ `'task-completed'`) removes a whole class of copy-paste
+drift where the const is renamed but the literal is not.
+
+## What it flags
+
+For every `export const` whose name ends in a role suffix (default `Event` / `Command` / `Query`) and
+whose zod object declares a `type: z.literal('…')` property, the literal must equal
+`kebab(constName minus the role suffix)`. A mismatch is reported and **autofixed** to the expected
+value.
+
+```ts
+// ✗ camelCase discriminant  →  autofixes to 'task-completed'
+export const TaskCompletedEvent = z.object({ type: z.literal('taskCompleted') });
+
+// ✗ wrong value              →  autofixes to 'run-task'
+export const RunTaskCommand = z.object({ type: z.literal('run') });
+
+// ✓
+export const TaskCompletedEvent = z.object({ type: z.literal('task-completed') });
+```
+
+Consts without a role suffix, and role-suffixed consts without a `type` literal, are ignored.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `roleSuffixes` | `string[]` | `['Event', 'Command', 'Query']` | Const-name suffixes that mark a schema as a wire message. |
+
+```js
+'noctcore-contracts/wire-message-naming': ['error', { roleSuffixes: ['Message'] }]
+```
+
+```ts
+// with roleSuffixes: ['Message']  →  autofixes to 'task-done'
+export const TaskDoneMessage = z.object({ type: z.literal('done') });
+```
+
+## When not to use it
+
+If your messages do not carry a role-suffixed const name plus a `type: z.literal(...)` discriminant,
+this rule never fires. Pair it with [`zod-schema-naming`](./zod-schema-naming.md) (listing the same
+suffixes there) so every export is covered by exactly one naming contract.

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

@@ -0,0 +1,54 @@
+# `noctcore-contracts/zod-schema-naming`
+
+> Every exported zod schema is a PascalCase const suffixed `Schema`, paired with a same-named inferred type.
+
+## Why
+
+A contracts package is a shared spine. A uniform `FooSchema` + `Foo` pairing keeps the schema and
+its TypeScript type discoverable and prevents a hand-authored duplicate type from drifting away from
+the schema it is supposed to mirror.
+
+## What it flags
+
+For every `export const` whose initializer is rooted at the `z` identifier (`z.object(...)`,
+`z.string().min(1)`, `z.union([...])`, …):
+
+- the const name must match `^[A-Z][A-Za-z0-9]*Schema$` — otherwise `schemaNaming`;
+- a correctly-named `FooSchema` must have a sibling `export type Foo` (a `type` alias or
+  `interface`) — otherwise `missingType`.
+
+```ts
+// ✗ not suffixed `Schema`
+export const Task = z.object({});
+
+// ✗ no sibling inferred type
+export const TaskSchema = z.object({});
+
+// ✓
+export const TaskSchema = z.object({ id: z.string() });
+export type Task = z.infer<typeof TaskSchema>;
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `roleSuffixes` | `string[]` | `[]` | Const-name suffixes that opt a schema **out** of the `*Schema` rule (their naming is owned by [`wire-message-naming`](./wire-message-naming.md)). |
+
+With the default empty list the base convention applies to every exported zod schema. Codebases that
+model wire messages as `*Event` / `*Command` / `*Query` discriminated-union members pass those
+suffixes to carve them out:
+
+```js
+'noctcore-contracts/zod-schema-naming': ['error', { roleSuffixes: ['Event', 'Command', 'Query'] }]
+```
+
+```ts
+// carved out only when 'Command' is listed in roleSuffixes
+export const RunTaskCommand = z.object({ type: z.literal('run-task') });
+```
+
+## When not to use it
+
+If your codebase does not import zod as `z`, or does not pair schemas with inferred types, this rule
+will not fit — it keys off the `z` root identifier and the `FooSchema`/`Foo` pairing convention.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@noctcore/eslint-plugin-contracts",
+  "version": "0.1.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",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "contracts",
+    "zod",
+    "noctcore"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "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",
+  "bugs": "https://github.com/noctcore/eslint-plugins/issues",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@noctcore/eslint-utils": "^0.1.0",
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@noctcore/eslint-test-utils": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "@typescript-eslint/rule-tester": "^8.61.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "vitest": "^3"
+  }
+}