@noctcore/eslint-plugin-contracts 0.6.1 → 0.7.1

package/dist/index.js

@@ -76,7 +76,8 @@ var envVarSchemaParityRule = createRule({
   meta: {
     type: "suggestion",
     docs: {
-      description: "Require every `process.env.FOO` / `import.meta.env.FOO` key to be declared in a schema file (`.env.example` or a zod-env module), so config access and config declaration cannot drift apart."
+      description: "Require every `process.env.FOO` / `import.meta.env.FOO` key to be declared in a schema file (`.env.example` or a zod-env module), so config access and config declaration cannot drift apart.",
+      requiresOptions: true
     },
     schema: [optionSchema],
     messages: {
@@ -1043,7 +1044,8 @@ var requireRegisteredKeysRule = createRule({
   meta: {
     type: "suggestion",
     docs: {
-      description: "Require the key/name argument of configured sink APIs (storage, event channels, cache keys) to be an imported constant from a registry module, not a raw string literal."
+      description: "Require the key/name argument of configured sink APIs (storage, event channels, cache keys) to be an imported constant from a registry module, not a raw string literal.",
+      requiresOptions: true
     },
     schema: [optionSchema6],
     messages: {
@@ -1093,22 +1095,315 @@ var requireRegisteredKeysRule = createRule({
 });
 
 // src/rules/require-schema-parse-at-boundary.ts
-import { AST_NODE_TYPES as AST_NODE_TYPES8 } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES as AST_NODE_TYPES8, ASTUtils } from "@typescript-eslint/utils";
 var RULE_NAME8 = "require-schema-parse-at-boundary";
+var optionSchema7 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    boundaries: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      uniqueItems: true
+    }
+  }
+};
+function parentOf(node) {
+  return node.parent ?? null;
+}
+function memberPath(node) {
+  if (node.type === AST_NODE_TYPES8.Identifier) {
+    return node.name;
+  }
+  if (node.type === AST_NODE_TYPES8.MemberExpression && !node.computed && node.property.type === AST_NODE_TYPES8.Identifier) {
+    const object = memberPath(node.object);
+    return object === null ? null : `${object}.${node.property.name}`;
+  }
+  return null;
+}
+function methodCallReceiver(node, names) {
+  if (node.type === AST_NODE_TYPES8.CallExpression && node.callee.type === AST_NODE_TYPES8.MemberExpression && !node.callee.computed && node.callee.property.type === AST_NODE_TYPES8.Identifier && names.includes(node.callee.property.name)) {
+    return node.callee.object;
+  }
+  return null;
+}
+function unwrap(node) {
+  let current = node;
+  while (current.type === AST_NODE_TYPES8.TSNonNullExpression || current.type === AST_NODE_TYPES8.ChainExpression) {
+    current = current.expression;
+  }
+  return current;
+}
 function isJsonParseCall(node) {
-  return node.type === AST_NODE_TYPES8.CallExpression && node.callee.type === AST_NODE_TYPES8.MemberExpression && !node.callee.computed && node.callee.object.type === AST_NODE_TYPES8.Identifier && node.callee.object.name === "JSON" && node.callee.property.type === AST_NODE_TYPES8.Identifier && node.callee.property.name === "parse";
+  return node.type === AST_NODE_TYPES8.CallExpression && memberPath(node.callee) === "JSON.parse";
 }
 function isAwaitJsonCall(node) {
   if (node.type !== AST_NODE_TYPES8.AwaitExpression) {
     return false;
   }
   const call = node.argument;
-  return call.type === AST_NODE_TYPES8.CallExpression && call.arguments.length === 0 && call.callee.type === AST_NODE_TYPES8.MemberExpression && !call.callee.computed && call.callee.property.type === AST_NODE_TYPES8.Identifier && call.callee.property.name === "json";
+  return methodCallReceiver(call, ["json"]) !== null && call.type === AST_NODE_TYPES8.CallExpression && call.arguments.length === 0;
+}
+function isStorageRead(node) {
+  const receiver = methodCallReceiver(node, ["getItem"]);
+  const path3 = receiver === null ? null : memberPath(receiver);
+  if (path3 === null) {
+    return false;
+  }
+  const last = path3.slice(path3.lastIndexOf(".") + 1);
+  return last === "localStorage" || last === "sessionStorage";
+}
+var BoundaryMatcher = class {
+  sourceCode;
+  boundaries;
+  constructor(sourceCode, boundaries) {
+    this.sourceCode = sourceCode;
+    this.boundaries = new Set(boundaries);
+  }
+  /** True when `expr`, the operand of the cast at `cast`, is boundary data. */
+  isBoundary(expr, cast, seen) {
+    const node = unwrap(expr);
+    if (isJsonParseCall(node) || isAwaitJsonCall(node) || isStorageRead(node) || this.isSearchParamsRead(node) || this.isConfiguredBoundary(node) || this.isMessageEventData(node) || this.isToolUseInput(node)) {
+      return true;
+    }
+    if (node.type !== AST_NODE_TYPES8.Identifier) {
+      return false;
+    }
+    const variable = this.resolve(node);
+    if (variable === null || seen.has(variable)) {
+      return false;
+    }
+    seen.add(variable);
+    const init = this.constInit(variable);
+    return init !== null && this.untouchedBefore(variable, node, cast) && this.isBoundary(init, init, seen);
+  }
+  resolve(identifier) {
+    return ASTUtils.findVariable(this.sourceCode.getScope(identifier), identifier) ?? null;
+  }
+  /** The initializer of a single `const name = <init>` declaration, or null. */
+  constInit(variable) {
+    const [def] = variable.defs;
+    if (variable.defs.length !== 1 || def === void 0) {
+      return null;
+    }
+    const declarator = def.node;
+    if (declarator.type !== AST_NODE_TYPES8.VariableDeclarator || declarator.id.type !== AST_NODE_TYPES8.Identifier || declarator.init === null) {
+      return null;
+    }
+    const declaration = parentOf(declarator);
+    if (declaration?.type !== AST_NODE_TYPES8.VariableDeclaration || declaration.kind !== "const") {
+      return null;
+    }
+    return declarator.init;
+  }
+  /**
+   * True when the only reads of `variable` that could run before `cast` are the
+   * `use` itself and other `as` casts, all in the declaring function. Any other
+   * earlier read (a guard, a validator call, a mutation) might have checked the
+   * value, so the cast is given the benefit of the doubt.
+   */
+  untouchedBefore(variable, use, cast) {
+    const home = variable.scope.variableScope;
+    return variable.references.every((reference) => {
+      if (reference.init === true) {
+        return true;
+      }
+      if (reference.from.variableScope !== home) {
+        return false;
+      }
+      const id = reference.identifier;
+      if (id === use || id.range[0] >= cast.range[0]) {
+        return true;
+      }
+      return parentOf(id)?.type === AST_NODE_TYPES8.TSAsExpression;
+    });
+  }
+  /** A call whose callee is listed in the `boundaries` option. */
+  isConfiguredBoundary(node) {
+    if (this.boundaries.size === 0) {
+      return false;
+    }
+    const call = node.type === AST_NODE_TYPES8.AwaitExpression ? unwrap(node.argument) : node;
+    if (call.type !== AST_NODE_TYPES8.CallExpression) {
+      return false;
+    }
+    const path3 = memberPath(call.callee);
+    return path3 !== null && this.boundaries.has(path3);
+  }
+  /** `.get(...)` / `.getAll(...)` on a `URLSearchParams`. */
+  isSearchParamsRead(node) {
+    const receiver = methodCallReceiver(node, ["get", "getAll"]);
+    return receiver !== null && this.isSearchParams(unwrap(receiver), /* @__PURE__ */ new Set());
+  }
+  isSearchParams(node, seen) {
+    if (node.type === AST_NODE_TYPES8.NewExpression) {
+      return node.callee.type === AST_NODE_TYPES8.Identifier && node.callee.name === "URLSearchParams";
+    }
+    if (node.type === AST_NODE_TYPES8.MemberExpression) {
+      return !node.computed && node.property.type === AST_NODE_TYPES8.Identifier && node.property.name === "searchParams";
+    }
+    if (node.type !== AST_NODE_TYPES8.Identifier) {
+      return false;
+    }
+    if (node.name === "searchParams") {
+      return true;
+    }
+    const variable = this.resolve(node);
+    if (variable === null || seen.has(variable)) {
+      return false;
+    }
+    seen.add(variable);
+    const init = this.constInit(variable);
+    return init !== null && this.isSearchParams(unwrap(init), seen);
+  }
+  /** `event.data` (or a `{ data }` destructured parameter) in a `message` listener. */
+  isMessageEventData(node) {
+    let identifier;
+    if (node.type === AST_NODE_TYPES8.MemberExpression) {
+      if (node.computed || node.property.type !== AST_NODE_TYPES8.Identifier || node.property.name !== "data" || node.object.type !== AST_NODE_TYPES8.Identifier) {
+        return false;
+      }
+      identifier = node.object;
+    } else if (node.type === AST_NODE_TYPES8.Identifier) {
+      identifier = node;
+    } else {
+      return false;
+    }
+    const variable = this.resolve(identifier);
+    const param = variable === null ? null : parameterOf(variable);
+    if (param === null) {
+      return false;
+    }
+    const { fn, name } = param;
+    const [first] = fn.params;
+    if (first === void 0) {
+      return false;
+    }
+    const isParamItself = name === first;
+    const isDestructuredData = first.type === AST_NODE_TYPES8.ObjectPattern && first.properties.some(
+      (property) => property.type === AST_NODE_TYPES8.Property && !property.computed && property.key.type === AST_NODE_TYPES8.Identifier && property.key.name === "data" && property.value === name
+    );
+    if (node.type === AST_NODE_TYPES8.MemberExpression ? !isParamItself : !isDestructuredData) {
+      return false;
+    }
+    return isMessageListener(fn);
+  }
+  /** `block.input` where `block` is narrowed to an Anthropic `tool_use` content block. */
+  isToolUseInput(node) {
+    if (node.type !== AST_NODE_TYPES8.MemberExpression || node.computed || node.property.type !== AST_NODE_TYPES8.Identifier || node.property.name !== "input") {
+      return false;
+    }
+    const block = unwrap(node.object);
+    const blockText = this.sourceCode.getText(block);
+    if (this.isGuardedAsToolUse(node, blockText)) {
+      return true;
+    }
+    if (block.type !== AST_NODE_TYPES8.Identifier) {
+      return false;
+    }
+    const variable = this.resolve(block);
+    if (variable === null) {
+      return false;
+    }
+    const init = this.constInit(variable);
+    if (init !== null) {
+      const receiver = methodCallReceiver(unwrap(init), ["find"]);
+      const call = unwrap(init);
+      return receiver !== null && call.type === AST_NODE_TYPES8.CallExpression && this.isToolUsePredicate(call.arguments[0]);
+    }
+    const param = parameterOf(variable);
+    if (param !== null && param.fn.params[0] === param.name) {
+      const call = parentOf(param.fn);
+      if (call?.type !== AST_NODE_TYPES8.CallExpression || call.arguments[0] !== param.fn || methodCallReceiver(call, ["map", "flatMap", "forEach"]) === null) {
+        return false;
+      }
+      const filtered = unwrap(call.callee.object);
+      return methodCallReceiver(filtered, ["filter"]) !== null && filtered.type === AST_NODE_TYPES8.CallExpression && this.isToolUsePredicate(filtered.arguments[0]);
+    }
+    return false;
+  }
+  /** `(b) => b.type === 'tool_use'`, optionally with a type-predicate return. */
+  isToolUsePredicate(node) {
+    if (node?.type !== AST_NODE_TYPES8.ArrowFunctionExpression || node.body.type === AST_NODE_TYPES8.BlockStatement) {
+      return false;
+    }
+    const [param] = node.params;
+    return param?.type === AST_NODE_TYPES8.Identifier && this.testProvesToolUse(node.body, param.name);
+  }
+  /** An enclosing `if` / `?:` / `&&` / `case 'tool_use':` narrows `blockText`. */
+  isGuardedAsToolUse(from, blockText) {
+    let child = from;
+    for (let parent = parentOf(child); parent !== null; child = parent, parent = parentOf(child)) {
+      switch (parent.type) {
+        case AST_NODE_TYPES8.IfStatement:
+        case AST_NODE_TYPES8.ConditionalExpression:
+          if (parent.consequent === child && this.testProvesToolUse(parent.test, blockText)) {
+            return true;
+          }
+          break;
+        case AST_NODE_TYPES8.LogicalExpression:
+          if (parent.operator === "&&" && parent.right === child && this.testProvesToolUse(parent.left, blockText)) {
+            return true;
+          }
+          break;
+        case AST_NODE_TYPES8.SwitchCase: {
+          const statement = parentOf(parent);
+          if (parent.test?.type === AST_NODE_TYPES8.Literal && parent.test.value === "tool_use" && statement?.type === AST_NODE_TYPES8.SwitchStatement && this.sourceCode.getText(statement.discriminant) === `${blockText}.type`) {
+            return true;
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    return false;
+  }
+  /** `<blockText>.type === 'tool_use'`, possibly one conjunct of an `&&` chain. */
+  testProvesToolUse(test, blockText) {
+    if (test.type === AST_NODE_TYPES8.LogicalExpression && test.operator === "&&") {
+      return this.testProvesToolUse(test.left, blockText) || this.testProvesToolUse(test.right, blockText);
+    }
+    if (test.type !== AST_NODE_TYPES8.BinaryExpression || test.operator !== "===" && test.operator !== "==") {
+      return false;
+    }
+    const typeText = `${blockText}.type`;
+    const isToolUse = (node) => node.type === AST_NODE_TYPES8.Literal && node.value === "tool_use";
+    const isTypeRead = (node) => this.sourceCode.getText(unwrap(node)) === typeText || this.sourceCode.getText(node) === `${blockText}?.type`;
+    return isTypeRead(test.left) && isToolUse(test.right) || isToolUse(test.left) && isTypeRead(test.right);
+  }
+};
+function parameterOf(variable) {
+  const [def] = variable.defs;
+  if (variable.defs.length !== 1 || def === void 0 || def.type !== "Parameter") {
+    return null;
+  }
+  const fn = def.node;
+  if (fn.type !== AST_NODE_TYPES8.ArrowFunctionExpression && fn.type !== AST_NODE_TYPES8.FunctionDeclaration && fn.type !== AST_NODE_TYPES8.FunctionExpression) {
+    return null;
+  }
+  return { fn, name: def.name };
+}
+function isMessageListener(fn) {
+  const parent = parentOf(fn);
+  if (parent?.type === AST_NODE_TYPES8.CallExpression) {
+    const [event, listener] = parent.arguments;
+    const callee = memberPath(parent.callee);
+    return listener === fn && event?.type === AST_NODE_TYPES8.Literal && event.value === "message" && callee !== null && (callee === "addEventListener" || callee.endsWith(".addEventListener"));
+  }
+  if (parent?.type === AST_NODE_TYPES8.AssignmentExpression && parent.right === fn) {
+    const target = memberPath(parent.left);
+    return target !== null && (target === "onmessage" || target.endsWith(".onmessage"));
+  }
+  return false;
 }
 function isShapeClaim(annotation) {
   if (annotation.type === AST_NODE_TYPES8.TSArrayType) {
     return true;
   }
+  if (annotation.type === AST_NODE_TYPES8.TSUnionType || annotation.type === AST_NODE_TYPES8.TSIntersectionType) {
+    return annotation.types.some(isShapeClaim);
+  }
   if (annotation.type === AST_NODE_TYPES8.TSTypeReference) {
     return !(annotation.typeName.type === AST_NODE_TYPES8.Identifier && annotation.typeName.name === "const");
   }
@@ -1119,22 +1414,22 @@ var requireSchemaParseAtBoundaryRule = createRule({
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow asserting external boundary data with `as T` instead of parsing it at runtime. Flags `JSON.parse(...) as T` and `(await res.json()) as T`; use a zod/valibot parse."
+      description: "Disallow asserting external boundary data with `as T` instead of parsing it at runtime. Flags casts of `JSON.parse`, `res.json()`, web storage, URL search params, message-event data and LLM tool input, directly or through a `const`; use a zod/valibot parse."
     },
-    schema: [],
+    schema: [optionSchema7],
     messages: {
       castedBoundaryData: "Boundary data is asserted with `as` here, not parsed. A cast is unchecked \u2014 validate this with a runtime schema (e.g. `Schema.parse(...)`) so a wire-shape change fails loudly."
     }
   },
-  defaultOptions: [],
-  create(context) {
+  defaultOptions: [{}],
+  create(context, [options]) {
+    const matcher = new BoundaryMatcher(context.sourceCode, options.boundaries ?? []);
     return {
       TSAsExpression(node) {
         if (!isShapeClaim(node.typeAnnotation)) {
           return;
         }
-        const expr = node.expression;
-        if (isJsonParseCall(expr) || isAwaitJsonCall(expr)) {
+        if (matcher.isBoundary(node.expression, node, /* @__PURE__ */ new Set())) {
           context.report({ node, messageId: "castedBoundaryData" });
         }
       }
@@ -1146,7 +1441,7 @@ var requireSchemaParseAtBoundaryRule = createRule({
 import { AST_NODE_TYPES as AST_NODE_TYPES9 } from "@typescript-eslint/utils";
 var RULE_NAME9 = "restrict-throw-to-taxonomy";
 var DEFAULT_ALLOW = ["Error"];
-var optionSchema7 = {
+var optionSchema8 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -1177,7 +1472,7 @@ var restrictThrowToTaxonomyRule = createRule({
     docs: {
       description: "Restrict `throw` to an approved error taxonomy. Flags throwing a non-allowlisted error class and throwing a non-Error value (string, object, number, ...)."
     },
-    schema: [optionSchema7],
+    schema: [optionSchema8],
     messages: {
       disallowedErrorClass: "Throw an error from your taxonomy, not `{{name}}`. Allowed: {{allowed}}. Add `{{name}}` to the `allow` option if it belongs to your taxonomy.",
       nonErrorThrow: "Throw an Error from your taxonomy, not a bare {{kind}} value. A non-Error throw carries no stack or cause."
@@ -1232,7 +1527,7 @@ var ENUM_FACTORIES = /* @__PURE__ */ new Set(["enum", "nativeEnum"]);
 var UNION = /* @__PURE__ */ new Set(["union"]);
 var LITERAL = /* @__PURE__ */ new Set(["literal"]);
 var STRING = /* @__PURE__ */ new Set(["string"]);
-var optionSchema8 = {
+var optionSchema9 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -1267,7 +1562,7 @@ var schemaEnumFieldConsistencyRule = createRule({
     docs: {
       description: "Disallow a zod field that is an enum in one object schema of a module from being `z.string()` in another, which widens the wire type every consumer then narrows by hand."
     },
-    schema: [optionSchema8],
+    schema: [optionSchema9],
     messages: {
       widenedEnumField: "`{{field}}` is `z.string()` here but an enum on line {{line}} of this file. The widened type leaks `string` to every consumer, which then has to narrow or cast it. Use {{suggestion}} instead (and, if the stored data is free text, migrate it first)."
     }
@@ -1522,7 +1817,7 @@ function catalogHasPrefix(catalog, prefix) {
 import { AST_NODE_TYPES as AST_NODE_TYPES11 } from "@typescript-eslint/utils";
 var UNRESOLVED = "unresolved";
 var MAX_DEPTH = 8;
-function unwrap(node) {
+function unwrap2(node) {
   let current = node;
   while (current.type === AST_NODE_TYPES11.TSAsExpression || current.type === AST_NODE_TYPES11.TSSatisfiesExpression || current.type === AST_NODE_TYPES11.TSNonNullExpression) {
     current = current.expression;
@@ -1530,7 +1825,7 @@ function unwrap(node) {
   return current;
 }
 function staticString(node) {
-  const inner = unwrap(node);
+  const inner = unwrap2(node);
   if (inner.type === AST_NODE_TYPES11.Literal && typeof inner.value === "string") return inner.value;
   if (inner.type === AST_NODE_TYPES11.TemplateLiteral && inner.expressions.length === 0) {
     return inner.quasis[0]?.value.cooked ?? null;
@@ -1571,7 +1866,7 @@ function createTranslationVisitor(context, settings, onUsage) {
   }
   function resolveNamespaces(node, depth = 0) {
     if (node === void 0) return defaultBinding.namespaces;
-    const inner = unwrap(node);
+    const inner = unwrap2(node);
     const literal = staticString(inner);
     if (literal !== null) return [literal];
     if (inner.type === AST_NODE_TYPES11.Literal && inner.value === null) return defaultBinding.namespaces;
@@ -1596,7 +1891,7 @@ function createTranslationVisitor(context, settings, onUsage) {
     }
     const definition = resolveVariable(node)?.defs[0];
     if (definition?.type === "Variable" && definition.parent.kind === "const" && definition.node.id.type === AST_NODE_TYPES11.Identifier && definition.node.init !== null) {
-      const init = unwrap(definition.node.init);
+      const init = unwrap2(definition.node.init);
       const literal = staticString(init);
       if (literal !== null) return literal;
       const chained = resolveIdentifierString(init, depth + 1);
@@ -1612,7 +1907,7 @@ function createTranslationVisitor(context, settings, onUsage) {
   }
   function staticPrefix(node) {
     if (node === void 0) return null;
-    const inner = unwrap(node);
+    const inner = unwrap2(node);
     if (inner.type === AST_NODE_TYPES11.Identifier && inner.name === "undefined") return null;
     if (inner.type === AST_NODE_TYPES11.Literal && inner.value === null) return null;
     return staticString(inner) ?? UNRESOLVED;
@@ -1623,7 +1918,7 @@ function createTranslationVisitor(context, settings, onUsage) {
     if (namespaces === UNRESOLVED) return UNRESOLVED;
     let keyPrefix = null;
     if (optionsArg !== void 0) {
-      const options = unwrap(optionsArg);
+      const options = unwrap2(optionsArg);
       if (options.type !== AST_NODE_TYPES11.ObjectExpression) return UNRESOLVED;
       for (const property of options.properties) {
         if (property.type !== AST_NODE_TYPES11.Property) return UNRESOLVED;
@@ -1649,11 +1944,11 @@ function createTranslationVisitor(context, settings, onUsage) {
   function hookCallOf(identifier) {
     const definition = resolveVariable(identifier)?.defs[0];
     if (definition?.type !== "Variable" || definition.node.id.type !== AST_NODE_TYPES11.Identifier) return null;
-    const init = definition.node.init === null ? null : unwrap(definition.node.init);
+    const init = definition.node.init === null ? null : unwrap2(definition.node.init);
     return init !== null && isHookCall(init) ? init : null;
   }
   function bindingOfTSource(object) {
-    const inner = unwrap(object);
+    const inner = unwrap2(object);
     if (isHookCall(inner)) return bindingFromHook(inner);
     if (inner.type === AST_NODE_TYPES11.Identifier) {
       const hook = hookCallOf(inner);
@@ -1690,7 +1985,7 @@ function createTranslationVisitor(context, settings, onUsage) {
   }
   function bindingFromDeclarator(declarator, name, depth) {
     if (declarator.init === null) return null;
-    const init = unwrap(declarator.init);
+    const init = unwrap2(declarator.init);
     const id = declarator.id;
     if (id.type === AST_NODE_TYPES11.Identifier) {
       if (isGetFixedT(init)) return bindingFromGetFixedT(init);
@@ -1751,7 +2046,7 @@ function createTranslationVisitor(context, settings, onUsage) {
   function readCallOptions(node) {
     const none = { namespaces: null, plural: false, context: false, returnObjects: false };
     if (node === void 0) return none;
-    const inner = unwrap(node);
+    const inner = unwrap2(node);
     if (inner.type !== AST_NODE_TYPES11.ObjectExpression) return UNRESOLVED;
     let namespaces = null;
     let plural = false;
@@ -1770,7 +2065,7 @@ function createTranslationVisitor(context, settings, onUsage) {
       } else if (name === "context") {
         context2 = true;
       } else if (name === "returnObjects") {
-        const value = unwrap(property.value);
+        const value = unwrap2(property.value);
         returnObjects = !(value.type === AST_NODE_TYPES11.Literal && value.value === false);
       }
     }
@@ -1790,7 +2085,7 @@ function createTranslationVisitor(context, settings, onUsage) {
     return { namespaces, key: `${binding.keyPrefix}${keySeparator === false ? "" : keySeparator}${raw}` };
   }
   function emit(node, keyNode, binding, options) {
-    const inner = unwrap(keyNode);
+    const inner = unwrap2(keyNode);
     const raws = [];
     const single = staticString(inner);
     if (single !== null) {
@@ -1913,7 +2208,7 @@ function createTranslationVisitor(context, settings, onUsage) {
 var RULE_NAME11 = "translation-key-exists";
 var stringList = { type: "array", items: { type: "string", minLength: 1 }, uniqueItems: true };
 var separator = { oneOf: [{ type: "string", minLength: 1 }, { type: "boolean", enum: [false] }] };
-var optionSchema9 = {
+var optionSchema10 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -1975,9 +2270,10 @@ var translationKeyExistsRule = createRule({
   meta: {
     type: "problem",
     docs: {
-      description: "Require every static i18next / react-i18next translation key (`t(...)`, `i18n.t(...)`, `<Trans i18nKey>`) to exist in the catalog of the namespace in scope."
+      description: "Require every static i18next / react-i18next translation key (`t(...)`, `i18n.t(...)`, `<Trans i18nKey>`) to exist in the catalog of the namespace in scope.",
+      requiresOptions: true
     },
-    schema: [optionSchema9],
+    schema: [optionSchema10],
     messages: {
       missingKey: "Translation key `{{key}}` does not exist in namespace `{{namespace}}` ({{catalogs}}). It renders as the raw key at runtime: fix the key or add it to the catalog.",
       missingKeyPrefix: "No key in namespace `{{namespace}}` ({{catalogs}}) starts with `{{prefix}}`, so this template key can never resolve.",
@@ -2066,7 +2362,7 @@ var translationKeyExistsRule = createRule({
 // src/rules/wire-message-naming.ts
 var RULE_NAME12 = "wire-message-naming";
 var DEFAULT_ROLE_SUFFIXES = ["Event", "Command", "Query"];
-var optionSchema10 = {
+var optionSchema11 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -2114,7 +2410,7 @@ var wireMessageNamingRule = createRule({
       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: [optionSchema10],
+    schema: [optionSchema11],
     messages: {
       typeMismatch: "Wire `type` literal '{{actual}}' for `{{name}}` must be '{{expected}}' \u2014 kebab-case of the const name minus its role suffix."
     }
@@ -2154,7 +2450,7 @@ var RULE_NAME13 = "zod-schema-naming";
 var SCHEMA_NAME = /^[A-Z][A-Za-z0-9]*Schema$/;
 var SUFFIX = "Schema";
 var DEFAULT_ROLE_SUFFIXES2 = [];
-var optionSchema11 = {
+var optionSchema12 = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -2193,7 +2489,7 @@ var zodSchemaNamingRule = createRule({
     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: [optionSchema11],
+    schema: [optionSchema12],
     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."
@@ -2262,7 +2558,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-contracts";
-var VERSION = "0.6.1";
+var VERSION = "0.7.1";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-contracts", version: VERSION },
   rules,

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

@@ -2,6 +2,10 @@
 
 > Every `process.env.FOO` / `import.meta.env.FOO` key must be declared in a schema file.
 
+<!-- begin generated rule header -->
+⚙️ Opt-in: `off` in `recommended`; needs options (see Options) · 💭 Type information: not needed
+<!-- end generated rule header -->
+
 ## Why
 
 An env var that is read in code but declared nowhere is config drift waiting to fail in production:
@@ -27,8 +31,12 @@ 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.
+## What it does not flag
+
+- Computed reads such as `process.env[dynamicKey]`: only static `.FOO` accesses are policed.
+- Destructured reads (`const { FOO } = process.env`).
+- Anything at all when `schema` is unset, or when the schema file cannot be read: the rule goes inert
+  rather than flagging every access.
 
 ## Options
 

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

@@ -2,7 +2,9 @@
 
 > 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).
+<!-- begin generated rule header -->
+✅ In `recommended` at `error` · 💭 Type information: not needed
+<!-- end generated rule header -->
 
 ## Why
 
@@ -85,6 +87,13 @@ Three response shapes are tracked: `const res = await fetch(...)` then `res.json
 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.
 
+## What it does not flag
+
+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`.
+
 ## Options
 
 | Option | Type | Default | Meaning |
@@ -99,9 +108,12 @@ List every name you want tracked, including `fetch` itself:
 }]
 ```
 
-## Limits
+## When not to use it
 
-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`.
+Leave it off if your code never reads a raw `Response`, for example when every request goes through a
+client whose `.json()` already throws on a bad status.
+
+## Credits
+
+Based on the `typescript-core/fetch-must-check-ok` rule from
+[tsforge](https://github.com/boringstack-xyz/tsforge) (MIT).