@noctcore/eslint-plugin-contracts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+interface MoneyMustBeDecimalOptions {
+    /** Name of the domain money type to require (e.g. `Decimal`, `Money`, `BigDecimal`). */
+    readonly decimalType?: string;
+    /** Regex fragments (case-insensitive) identifying money-named fields. */
+    readonly fieldPatterns?: readonly string[];
+    /** Path-suffix allowlist of files to skip entirely. */
+    readonly allowedFiles?: readonly string[];
+}
+
+interface NoDirectProcessEnvOptions {
+    /** Import path of the typed config accessor consumers should read env through. */
+    readonly configModule?: string;
+    /** Glob allowlist of files permitted to read `process.env` directly (bootstrap, config, tests). */
+    readonly allowedFiles?: readonly string[];
+}
+
+interface NoErrorStringifyOptions {
+    readonly errorIdentifierNames?: readonly string[];
+}
+
+interface WireMessageNamingOptions {
+    readonly roleSuffixes?: readonly string[];
+}
+
+interface ZodSchemaNamingOptions {
+    readonly roleSuffixes?: readonly string[];
+}
+
+/** Every rule this plugin exposes, keyed by its (unprefixed) rule id. */
+declare const rules: {
+    'zod-schema-naming': _typescript_eslint_utils_ts_eslint.RuleModule<"schemaNaming" | "missingType", [ZodSchemaNamingOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'wire-message-naming': _typescript_eslint_utils_ts_eslint.RuleModule<"typeMismatch", [WireMessageNamingOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'no-error-stringify': _typescript_eslint_utils_ts_eslint.RuleModule<"noErrorStringify", [NoErrorStringifyOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'no-direct-process-env': _typescript_eslint_utils_ts_eslint.RuleModule<"directProcessEnv", [NoDirectProcessEnvOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'money-must-be-decimal': _typescript_eslint_utils_ts_eslint.RuleModule<"moneyMustBeDecimal", [MoneyMustBeDecimalOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+};
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'zod-schema-naming': _typescript_eslint_utils_ts_eslint.RuleModule<"schemaNaming" | "missingType", [ZodSchemaNamingOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'wire-message-naming': _typescript_eslint_utils_ts_eslint.RuleModule<"typeMismatch", [WireMessageNamingOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'no-error-stringify': _typescript_eslint_utils_ts_eslint.RuleModule<"noErrorStringify", [NoErrorStringifyOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'no-direct-process-env': _typescript_eslint_utils_ts_eslint.RuleModule<"directProcessEnv", [NoDirectProcessEnvOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'money-must-be-decimal': _typescript_eslint_utils_ts_eslint.RuleModule<"moneyMustBeDecimal", [MoneyMustBeDecimalOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+    };
+    configs: Record<string, unknown>;
+};
+
+declare const configs: Record<string, unknown>;
+
+export { configs, plugin as default, rules };

package/dist/index.js

@@ -0,0 +1,516 @@
+// src/configs/recommended.ts
+var recommended = {
+  "noctcore-contracts/zod-schema-naming": "error",
+  "noctcore-contracts/wire-message-naming": "error",
+  "noctcore-contracts/no-error-stringify": "error",
+  "noctcore-contracts/no-direct-process-env": "error",
+  "noctcore-contracts/money-must-be-decimal": "error"
+};
+
+// src/rules/money-must-be-decimal.ts
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+
+// src/createRule.ts
+import { makeCreateRule } from "@noctcore/eslint-utils";
+var createRule = makeCreateRule("contracts");
+
+// src/rules/money-must-be-decimal.ts
+var RULE_NAME = "money-must-be-decimal";
+var DEFAULT_DECIMAL_TYPE = "Decimal";
+var DEFAULT_FIELD_PATTERNS = [
+  "amount",
+  "price",
+  "cost",
+  "total",
+  "balance"
+];
+var DEFAULT_ALLOWED_FILES = [];
+var optionSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    decimalType: { type: "string", minLength: 1 },
+    fieldPatterns: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1
+    },
+    allowedFiles: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true
+    }
+  }
+};
+function toForwardSlash(filename) {
+  return filename.split("\\").join("/");
+}
+function isAllowedFile(filename, patterns) {
+  if (patterns.length === 0) {
+    return false;
+  }
+  const normalized = toForwardSlash(filename);
+  return patterns.some((pattern) => normalized.endsWith(toForwardSlash(pattern)));
+}
+function staticName(node) {
+  if (node.type === AST_NODE_TYPES.Identifier) {
+    return node.name;
+  }
+  return void 0;
+}
+function isNumberAnnotation(annotation) {
+  return annotation?.typeAnnotation.type === AST_NODE_TYPES.TSNumberKeyword;
+}
+var moneyMustBeDecimalRule = createRule({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow monetary values typed as the JS primitive `number`. Money-named fields explicitly typed `: number` lose precision to float rounding; use a Decimal money type instead."
+    },
+    schema: [optionSchema],
+    messages: {
+      moneyMustBeDecimal: "Monetary values must use {{decimalType}}, never the JS `number` primitive, to avoid float rounding errors. Rename or retype this field to a {{decimalType}} money type."
+    }
+  },
+  defaultOptions: [
+    {
+      decimalType: DEFAULT_DECIMAL_TYPE,
+      fieldPatterns: [...DEFAULT_FIELD_PATTERNS],
+      allowedFiles: []
+    }
+  ],
+  create(context, [options]) {
+    const decimalType = options.decimalType ?? DEFAULT_DECIMAL_TYPE;
+    const allowedFiles = options.allowedFiles ?? DEFAULT_ALLOWED_FILES;
+    if (isAllowedFile(context.filename, allowedFiles)) {
+      return {};
+    }
+    const fieldPatterns = options.fieldPatterns ?? DEFAULT_FIELD_PATTERNS;
+    const moneyPattern = new RegExp(`(${fieldPatterns.join("|")})`, "i");
+    function report(node) {
+      context.report({ node, messageId: "moneyMustBeDecimal", data: { decimalType } });
+    }
+    return {
+      // `class Invoice { total: number }`: class field explicitly typed number.
+      PropertyDefinition(node) {
+        if (node.computed) {
+          return;
+        }
+        const name = staticName(node.key);
+        if (name !== void 0 && moneyPattern.test(name) && isNumberAnnotation(node.typeAnnotation)) {
+          report(node);
+        }
+      },
+      // `const total: number = ...`: annotated variable declarator.
+      VariableDeclarator(node) {
+        if (node.id.type !== AST_NODE_TYPES.Identifier) {
+          return;
+        }
+        const name = node.id.name;
+        if (moneyPattern.test(name) && isNumberAnnotation(node.id.typeAnnotation)) {
+          report(node);
+        }
+      }
+    };
+  }
+});
+
+// src/rules/no-direct-process-env.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES2 } from "@typescript-eslint/utils";
+var RULE_NAME2 = "no-direct-process-env";
+var DEFAULT_CONFIG_MODULE = "@/config";
+var DEFAULT_ALLOWED_FILES2 = [
+  "**/*.config.{ts,js,mjs,cjs}",
+  "**/*.{spec,test}.{ts,tsx}",
+  "**/scripts/**"
+];
+var optionSchema2 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    configModule: { type: "string", minLength: 1 },
+    allowedFiles: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true
+    }
+  }
+};
+function globToRegExp(glob) {
+  let re = "";
+  let braceDepth = 0;
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        i++;
+        if (glob[i + 1] === "/") {
+          i++;
+          re += "(?:.*/)?";
+        } else {
+          re += ".*";
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (c === "{") {
+      re += "(?:";
+      braceDepth++;
+    } else if (c === "}") {
+      re += ")";
+      if (braceDepth > 0) braceDepth--;
+    } else if (c === ",") {
+      re += braceDepth > 0 ? "|" : "\\,";
+    } else if (".+^$()|[]\\/".includes(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function isAllowedFile2(filename, patterns) {
+  if (patterns.length === 0) {
+    return false;
+  }
+  const normalized = filename.split("\\").join("/");
+  return patterns.some((pattern) => globToRegExp(pattern).test(normalized));
+}
+function isProcessEnv(node) {
+  if (node.type !== AST_NODE_TYPES2.MemberExpression || node.object.type !== AST_NODE_TYPES2.Identifier || node.object.name !== "process") {
+    return false;
+  }
+  if (node.computed) {
+    return node.property.type === AST_NODE_TYPES2.Literal && node.property.value === "env";
+  }
+  return node.property.type === AST_NODE_TYPES2.Identifier && node.property.name === "env";
+}
+var noDirectProcessEnvRule = createRule({
+  name: RULE_NAME2,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow direct `process.env` access. Force every consumer through a typed, validated config accessor so a missing variable fails at boot, not at use."
+    },
+    schema: [optionSchema2],
+    messages: {
+      directProcessEnv: "Read environment variables through your typed config accessor (import from `{{configModule}}`). Direct `process.env` access bypasses boot-time validation."
+    }
+  },
+  defaultOptions: [
+    {
+      configModule: DEFAULT_CONFIG_MODULE,
+      allowedFiles: [...DEFAULT_ALLOWED_FILES2]
+    }
+  ],
+  create(context, [options]) {
+    const configModule = options.configModule ?? DEFAULT_CONFIG_MODULE;
+    const allowedFiles = options.allowedFiles ?? DEFAULT_ALLOWED_FILES2;
+    if (isAllowedFile2(context.filename, allowedFiles)) {
+      return {};
+    }
+    return {
+      /*
+       * `process.env` is itself a MemberExpression, so a single visitor on the
+       * node catches every usage position: property access (`process.env.X`),
+       * computed access (`process.env[X]`), destructuring (`const { X } =
+       * process.env`), and bare value usage where it is passed as an argument,
+       * returned, or assigned (`log(process.env)`, `return process.env`).
+       */
+      MemberExpression(node) {
+        if (isProcessEnv(node)) {
+          context.report({ node, messageId: "directProcessEnv", data: { configModule } });
+        }
+      }
+    };
+  }
+});
+
+// src/rules/no-error-stringify.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES3 } from "@typescript-eslint/utils";
+var RULE_NAME3 = "no-error-stringify";
+var DEFAULT_ERROR_NAMES = ["error", "err", "e", "cause"];
+var optionSchema3 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    errorIdentifierNames: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1
+    }
+  }
+};
+function isEmptyStringLiteral(node) {
+  return node.type === AST_NODE_TYPES3.Literal && node.value === "";
+}
+function isErrorIdentifier(node, names) {
+  return node.type === AST_NODE_TYPES3.Identifier && names.has(node.name);
+}
+var noErrorStringifyRule = createRule({
+  name: RULE_NAME3,
+  meta: {
+    type: "problem",
+    docs: {
+      description: 'Disallow stringifying an error with bare `${error}` interpolation, `error.toString()`, or `error + ""`. These drop the cause chain. Use `error instanceof Error ? error.message : String(error)` instead.'
+    },
+    schema: [optionSchema3],
+    messages: {
+      noErrorStringify: "Stringifying an error this way drops its cause chain. Use `{{name}} instanceof Error ? {{name}}.message : String({{name}})` (or pass the Error object straight to the logger)."
+    }
+  },
+  defaultOptions: [{ errorIdentifierNames: [...DEFAULT_ERROR_NAMES] }],
+  create(context, [options]) {
+    const errorNames = new Set(options.errorIdentifierNames ?? DEFAULT_ERROR_NAMES);
+    function report(node, name) {
+      context.report({ node, messageId: "noErrorStringify", data: { name } });
+    }
+    return {
+      // `error.toString()`
+      'CallExpression[callee.type="MemberExpression"]'(node) {
+        const callee = node.callee;
+        if (!callee.computed && callee.property.type === AST_NODE_TYPES3.Identifier && callee.property.name === "toString" && node.arguments.length === 0 && isErrorIdentifier(callee.object, errorNames)) {
+          report(node, callee.object.name);
+        }
+      },
+      // bare `${error}` inside a template literal
+      TemplateLiteral(node) {
+        for (const expr of node.expressions) {
+          if (isErrorIdentifier(expr, errorNames)) {
+            report(expr, expr.name);
+          }
+        }
+      },
+      // `error + ""` or `"" + error`
+      BinaryExpression(node) {
+        if (node.operator !== "+") {
+          return;
+        }
+        const sides = [node.left, node.right];
+        if (!sides.some(isEmptyStringLiteral)) {
+          return;
+        }
+        for (const side of sides) {
+          if (isErrorIdentifier(side, errorNames)) {
+            report(node, side.name);
+            return;
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/rules/wire-message-naming.ts
+var RULE_NAME4 = "wire-message-naming";
+var DEFAULT_ROLE_SUFFIXES = ["Event", "Command", "Query"];
+var optionSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    roleSuffixes: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+      minItems: 1
+    }
+  }
+};
+function kebab(input) {
+  return input.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase();
+}
+function roleSuffix(name, suffixes) {
+  return suffixes.find((s) => name.endsWith(s) && name.length > s.length) ?? null;
+}
+function unwrapToObject(node) {
+  let cur = node;
+  while (cur && cur.type === "CallExpression") {
+    const objArg = cur.arguments.find((a) => a.type === "ObjectExpression");
+    if (objArg && objArg.type === "ObjectExpression") return objArg;
+    cur = cur.callee.type === "MemberExpression" ? cur.callee.object : null;
+  }
+  return null;
+}
+function typeLiteralNode(obj) {
+  for (const p of obj.properties) {
+    if (p.type !== "Property") continue;
+    const isType = p.key.type === "Identifier" && p.key.name === "type" || p.key.type === "Literal" && p.key.value === "type";
+    if (!isType) continue;
+    const v = p.value;
+    if (v.type === "CallExpression" && v.callee.type === "MemberExpression" && v.callee.property.type === "Identifier" && v.callee.property.name === "literal") {
+      const arg = v.arguments[0];
+      if (arg && arg.type === "Literal" && typeof arg.value === "string") return arg;
+    }
+  }
+  return null;
+}
+var wireMessageNamingRule = createRule({
+  name: RULE_NAME4,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A message-schema const ending in a role suffix (default Event/Command/Query) whose zod object declares `type: z.literal(...)` must set that literal to kebab-case(const name minus its role suffix)."
+    },
+    fixable: "code",
+    schema: [optionSchema4],
+    messages: {
+      typeMismatch: "Wire `type` literal '{{actual}}' for `{{name}}` must be '{{expected}}' \u2014 kebab-case of the const name minus its role suffix."
+    }
+  },
+  defaultOptions: [{ roleSuffixes: ["Event", "Command", "Query"] }],
+  create(context, [options]) {
+    const roleSuffixes = options.roleSuffixes ?? DEFAULT_ROLE_SUFFIXES;
+    return {
+      ExportNamedDeclaration(node) {
+        const decl = node.declaration;
+        if (!decl || decl.type !== "VariableDeclaration") return;
+        for (const d of decl.declarations) {
+          if (d.id.type !== "Identifier" || !d.init) continue;
+          const suffix = roleSuffix(d.id.name, roleSuffixes);
+          if (!suffix) continue;
+          const obj = unwrapToObject(d.init);
+          if (!obj) continue;
+          const lit = typeLiteralNode(obj);
+          if (!lit) continue;
+          const expected = kebab(d.id.name.slice(0, -suffix.length));
+          if (lit.value !== expected) {
+            context.report({
+              node: lit,
+              messageId: "typeMismatch",
+              data: { name: d.id.name, actual: String(lit.value), expected },
+              fix: (fixer) => fixer.replaceText(lit, `'${expected}'`)
+            });
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/rules/zod-schema-naming.ts
+var RULE_NAME5 = "zod-schema-naming";
+var SCHEMA_NAME = /^[A-Z][A-Za-z0-9]*Schema$/;
+var SUFFIX = "Schema";
+var DEFAULT_ROLE_SUFFIXES2 = [];
+var optionSchema5 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    roleSuffixes: {
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true
+    }
+  }
+};
+function hasRoleSuffix(name, suffixes) {
+  return suffixes.some((s) => name.endsWith(s) && name.length > s.length);
+}
+function rootIdentifierName(node) {
+  let current = node;
+  while (current) {
+    switch (current.type) {
+      case "CallExpression":
+        current = current.callee;
+        break;
+      case "MemberExpression":
+        current = current.object;
+        break;
+      case "Identifier":
+        return current.name;
+      default:
+        return null;
+    }
+  }
+  return null;
+}
+var zodSchemaNamingRule = createRule({
+  name: RULE_NAME5,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Every exported zod schema is a PascalCase const suffixed `Schema`, paired with a same-named inferred type (`export type Foo = z.infer<typeof FooSchema>`)."
+    },
+    schema: [optionSchema5],
+    messages: {
+      schemaNaming: "Exported zod schema `{{name}}` must be a PascalCase const ending in `Schema` (e.g. `FooSchema`).",
+      missingType: "Schema `{{name}}` has no sibling `export type {{base}} = z.infer<typeof {{name}}>`. Export the inferred type instead of hand-authoring a duplicate."
+    }
+  },
+  defaultOptions: [{ roleSuffixes: [] }],
+  create(context, [options]) {
+    const roleSuffixes = options.roleSuffixes ?? DEFAULT_ROLE_SUFFIXES2;
+    const schemas = [];
+    const exportedTypes = /* @__PURE__ */ new Set();
+    return {
+      ExportNamedDeclaration(node) {
+        const decl = node.declaration;
+        if (!decl) return;
+        if (decl.type === "VariableDeclaration") {
+          for (const d of decl.declarations) {
+            if (d.id.type === "Identifier" && d.init && rootIdentifierName(d.init) === "z") {
+              if (hasRoleSuffix(d.id.name, roleSuffixes)) continue;
+              if (!SCHEMA_NAME.test(d.id.name)) {
+                context.report({
+                  node: d.id,
+                  messageId: "schemaNaming",
+                  data: { name: d.id.name }
+                });
+              } else {
+                schemas.push({ node: d.id, name: d.id.name });
+              }
+            }
+          }
+        } else if (decl.type === "TSTypeAliasDeclaration" || decl.type === "TSInterfaceDeclaration") {
+          exportedTypes.add(decl.id.name);
+        }
+      },
+      "Program:exit"() {
+        for (const schema of schemas) {
+          const base = schema.name.slice(0, -SUFFIX.length);
+          if (!exportedTypes.has(base)) {
+            context.report({
+              node: schema.node,
+              messageId: "missingType",
+              data: { name: schema.name, base }
+            });
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/rules/index.ts
+var rules = {
+  "zod-schema-naming": zodSchemaNamingRule,
+  "wire-message-naming": wireMessageNamingRule,
+  "no-error-stringify": noErrorStringifyRule,
+  "no-direct-process-env": noDirectProcessEnvRule,
+  "money-must-be-decimal": moneyMustBeDecimalRule
+};
+
+// src/index.ts
+var NAMESPACE = "noctcore-contracts";
+var VERSION = "0.1.0";
+var plugin = {
+  meta: { name: "@noctcore/eslint-plugin-contracts", version: VERSION },
+  rules,
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: { [NAMESPACE]: plugin },
+  rules: recommended
+};
+var configs = plugin.configs;
+var index_default = plugin;
+export {
+  configs,
+  index_default as default,
+  rules
+};

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

@@ -0,0 +1,52 @@
+# `noctcore-contracts/money-must-be-decimal`
+
+> Monetary fields typed as the JS `number` primitive lose precision to float rounding — use a Decimal money type.
+
+## Why
+
+Money stored as a JS `number` accumulates IEEE-754 rounding errors (`0.1 + 0.2 !== 0.3`), which is
+unacceptable for accounting figures. This rule is a **dormant guard**: it stays green on a codebase
+with no money fields and lights up the moment a money-named field is introduced with the wrong type.
+
+## What it flags
+
+A field whose name matches the money pattern **and** is explicitly annotated `: number`, in the two
+positions that carry real precision risk:
+
+- class properties — `class Invoice { total: number }`
+- annotated variable declarators — `const amount: number = …`
+
+Conservative on purpose. Untyped declarations and numeric-literal initializers (`let total = 0`) are
+**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
+// ✗
+class Invoice { total: number; }
+const amount: number = 5;
+
+// ✓
+class Invoice { total: Decimal; }
+const count: number = 3;          // not a money name
+interface Payment { amount: number; }   // type member, out of scope
+```
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `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`). |
+
+```js
+'noctcore-contracts/money-must-be-decimal': ['error', {
+  decimalType: 'Money',
+  fieldPatterns: ['amount', 'price', 'discount', 'vat'],
+}]
+```
+
+## 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.

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

@@ -0,0 +1,51 @@
+# `noctcore-contracts/no-direct-process-env`
+
+> Read environment variables through a typed, validated config accessor — never `process.env` directly.
+
+## Why
+
+`process.env.X` is `string | undefined`, unvalidated, and reachable from anywhere. A typo or a missing
+variable fails silently at the point of use, often deep in a request. Funnelling every read through a
+single typed config module makes the environment a validated contract that fails **at boot**, and
+gives every consumer real types.
+
+## What it flags
+
+Any `process.env` access, in every position — property read (`process.env.X`), computed
+(`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
+// ✗
+const isProd = process.env.NODE_ENV === 'production';
+const { DATABASE_URL } = process.env;
+const env = process['env'];
+
+// ✓
+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.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `configModule` | `string` | `'@/config'` | Import path of the typed config accessor, named in the report message. |
+| `allowedFiles` | `string[]` (globs) | `['**/*.config.{ts,js,mjs,cjs}', '**/*.{spec,test}.{ts,tsx}', '**/scripts/**']` | Files permitted to read `process.env` directly. |
+
+Globs support `*`, `**`, `?`, and `{a,b}` alternation; a leading `**/` matches any (or no) directory
+prefix, so patterns work against both relative and absolute filenames.
+
+```js
+'noctcore-contracts/no-direct-process-env': ['error', {
+  configModule: '@acme/config',
+  allowedFiles: ['**/apps/server/**', '**/*.{spec,test}.{ts,tsx}'],
+}]
+```
+
+## When not to use it
+
+If you have no config seam yet, or intentionally read `process.env` throughout (a small script, a
+Vite-style `import.meta.env` app), leave this rule off or widen `allowedFiles`.