@sarj/eslint-plugin 16.36.5 → 16.36.7

package/dist/index.cjs

@@ -2314,8 +2314,13 @@ function commentSuppressesChecking(text, kind) {
 
 // src/rules/_closed-object-contract.ts
 var import_typescript2 = __toESM(require("typescript"), 1);
-function closedObjectContract(type, checker) {
-  return visitContract(type, { checker, active: /* @__PURE__ */ new Set(), completed: /* @__PURE__ */ new WeakMap() });
+function closedObjectContract(type, checker, singlePropertyOrigins = false) {
+  return visitContract(type, {
+    checker,
+    active: /* @__PURE__ */ new Set(),
+    completed: /* @__PURE__ */ new WeakMap(),
+    origins: singlePropertyOrigins ? /* @__PURE__ */ new Map() : void 0
+  });
 }
 function visitContract(type, proof) {
   const known2 = proof.completed.get(type);
@@ -2329,10 +2334,20 @@ function visitContract(type, proof) {
 }
 function completeObject(type, proof) {
   if (!ordinaryObject(type, proof.checker)) return false;
+  if (proof.origins && !singleOrigins(type, proof.origins)) return false;
   const declarations = type.getSymbol()?.getDeclarations()?.filter((declaration) => import_typescript2.default.isInterfaceDeclaration(declaration) || import_typescript2.default.isTypeLiteralNode(declaration));
   if (!declarations?.length) return false;
   return declarations.every((declaration) => completeDeclaration(declaration, proof));
 }
+function singleOrigins(type, origins) {
+  for (const property of type.getProperties()) {
+    const declarations = property.getDeclarations();
+    const declaration = declarations?.[0];
+    if (!declaration || declarations?.length !== 1 || origins.has(property.name) && origins.get(property.name) !== declaration) return false;
+    origins.set(property.name, declaration);
+  }
+  return true;
+}
 function ordinaryObject(type, checker) {
   if ((type.flags & import_typescript2.default.TypeFlags.Object) === 0 || type.isUnion() || checker.getIndexInfosOfType(type).length > 0) return false;
   const object = type;
@@ -2651,6 +2666,9 @@ function directEval(node) {
 function primitiveKeyword(node) {
   return node !== void 0 && (node.kind === import_typescript6.default.SyntaxKind.StringKeyword || node.kind === import_typescript6.default.SyntaxKind.NumberKeyword || node.kind === import_typescript6.default.SyntaxKind.BooleanKeyword || node.kind === import_typescript6.default.SyntaxKind.BigIntKeyword);
 }
+function nullishPrimitiveUnion(node) {
+  return node !== void 0 && import_typescript6.default.isUnionTypeNode(node) && node.types.length === 2 && node.types.some(primitiveKeyword) && node.types.some((part) => part.kind === import_typescript6.default.SyntaxKind.UndefinedKeyword || import_typescript6.default.isLiteralTypeNode(part) && part.literal.kind === import_typescript6.default.SyntaxKind.NullKeyword);
+}
 function consumerAnnotation(node) {
   if (node.params.length !== 1) return void 0;
   const parameter = node.params[0];
@@ -2708,6 +2726,8 @@ function directCalls(binding3) {
 // src/rules/no-redundant-consumer-union.ts
 var CONFIG = { path: "tsconfig.json", source: '{"compilerOptions":{"strict":true,"target":"ESNext","module":"ESNext","moduleResolution":"Bundler"}}' };
 var EXAMPLE = 'export {}; interface Animal {readonly name: string} interface Dog extends Animal {readonly breed: string} export type KeptDog = Dog; const dog: Dog = {name: "Ada", breed: "Collie"}; function label(value: Dog | Animal): string {return value.name;} label(dog);';
+var NULLABLE_EXAMPLE = EXAMPLE.replace("readonly name: string", "readonly name: string | null").replace("return value.name;", "return value.name ?? '';");
+var OPTIONAL_EXAMPLE = EXAMPLE.replace("readonly breed: string", "readonly breed?: string");
 var NO_REDUNDANT_CONSUMER_UNION_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Keep the covering object contract in a private scalar consumer union.",
@@ -2718,25 +2738,91 @@ var NO_REDUNDANT_CONSUMER_UNION_DOCUMENTATION = {
   limitations: [
     "Automatic fixes additionally require every existing identifier caller to be natively assignable to the original contract, without Any, unknown, error or unresolved types on the relevant surface. Comments inside the annotation and TypeScript suppression directives keep the finding manual. Removed named types/imports must retain an independent top-level exported type-alias or direct type-export read. Other removable annotations/assertions, the covering annotation and own-definition/self references cannot keep one another live; otherwise simultaneous fixes can introduce unused-type errors. The exact authored covering type and terminator token sequence are retained; edits that would merge distinct CR and LF terminators remain manual; no producer, call or function body is rewritten.",
     "Only an inline binary parameter union in a strict module's top-level private scalar consumer is supported. Exactly one parameter, an explicit broad primitive return annotation, a single pure returned scalar expression and direct identifier-argument callers are required. Type queries or type-only exports of the callable, public APIs, callbacks, contextual signatures, overloads, generics, decorators, async functions, direct eval and fresh-object callers prevent findings.",
-    "Both alternatives must have complete ordinary finite structural surfaces consisting only of explicitly readonly broad string, number, boolean or bigint properties. Aliases, imports, re-exports and ordinary inheritance are resolved by the parser-owned TypeScript checker. Any, unknown, missing imports, open/generic/mapped/indexed types, classes, brands, literal discriminants, methods, properties with scalar type aliases, callbacks and recursive or nested object fields are unsupported.",
-    "Reports only proper native assignability: covered is assignable to covering and the reverse is false. Every covering member, including optional members, must exist in the covered type's enumerated declared surface. Otherwise an existing identifier may carry an incompatible extra field and be rejected after simplification; implicit Object members containing Any also cannot witness coverage. The covering type must declare every read field and a read required field; an all-optional reduced contract can reject existing callers. Identical alternatives and primitive/top/bottom redundancy remain upstream-owned; mutually assignable but nonidentical structures are excluded.",
+    "Both alternatives must have complete ordinary finite structural surfaces consisting only of explicitly readonly broad string, number, boolean or bigint properties, optionally paired directly with null or undefined in an exact two-part union. Required and optional nullable fields may be read under the same native coverage proof. Every field must have one actual declaration origin throughout each alternative's inheritance/intersection graph. Shared ancestors retain that origin; repeated merged fields, explicit overrides and independently declared overlapping fields abstain, including valid compatible declarations. This excludes recovered conflicting properties without claiming whole-source health. Aliases, imports, re-exports and ordinary inheritance are resolved by the parser-owned TypeScript checker. Any, unknown, missing imports, open/generic/mapped/indexed types, classes, brands, literal discriminants, methods, properties with scalar type aliases, parenthesized or more complex property unions, callbacks and recursive or nested object fields are unsupported.",
+    "Reports proper native assignability, where covered is assignable to covering and the reverse is false, or mutual native assignability with a strict smaller declared covering surface and only optional covered-only members. Every covering member, including optional members, must exist in the covered type's enumerated declared surface. Otherwise an existing identifier may carry an incompatible extra field and be rejected after simplification; implicit Object members containing Any cannot replace explicit declared coverage or the native Optional requirement. The covering type must declare every read field and a read required field; an all-optional reduced contract can reject existing callers. Identical alternatives and primitive/top/bottom redundancy remain upstream-owned; equal-key and incomparable mutually assignable structures are excluded. The mutual case additionally requires inline contracts or locally bound interfaces/type aliases whose alias and heritage references can be traced through the parser-owned type scope. Merged interface fragments must all resolve to the reference's same native symbol; mixed exported/local recovery abstains. Imported, global and qualified-namespace references in that path abstain; proper one-way coverage retains its existing alias/import support.",
     "General union simplification can change Extract, conditional types, in-narrowing, fresh-literal checking and public presentation. Those contexts are excluded even when ordinary assignment succeeds. Flat destructuring counts every bound field as read; whole-object escape, mutation, helpers, closures, reflection, serialization, dynamic reads, implicit Object capabilities and JSX prevent findings. Imported Python protocol assignability is not approximated by this rule."
   ],
   examples: [
     { id: "covered-alternative", title: "The private consumer needs the covering Animal contract", outcome: "match", files: [{ path: "src/case.ts", source: EXAMPLE }, CONFIG], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: EXAMPLE.replace("Dog | Animal", "Animal") }] },
-    { id: "public-contract", title: "A public union retains its observable alternatives", outcome: "no-match", files: [{ path: "src/case.ts", source: EXAMPLE.replace("function label", "export function label") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true }
+    { id: "public-contract", title: "A public union retains its observable alternatives", outcome: "no-match", files: [{ path: "src/case.ts", source: EXAMPLE.replace("function label", "export function label") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true },
+    { id: "optional-covered-alternative", scenarioId: "optional-readonly-contract", title: "An unread optional breed retains the smaller Animal surface", outcome: "match", files: [{ path: "src/case.ts", source: OPTIONAL_EXAMPLE }, CONFIG], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: OPTIONAL_EXAMPLE.replace("Dog | Animal", "Animal") }] },
+    { id: "optional-public-contract", scenarioId: "optional-readonly-contract", title: "A public optional union retains its observable alternatives", outcome: "no-match", files: [{ path: "src/case.ts", source: OPTIONAL_EXAMPLE.replace("function label", "export function label") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true },
+    { id: "nullable-covered-alternative", scenarioId: "nullable-readonly-contract", title: "A nullable name retains the covering Animal contract", outcome: "match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE }, CONFIG], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("Dog | Animal", "Animal") }] },
+    { id: "nullable-domain-contract", scenarioId: "nullable-readonly-contract", title: "A literal breed keeps the authored domain contract", outcome: "no-match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("readonly breed: string", "readonly breed: 'Collie'") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true }
   ]
 };
 function scalarFields(type, checker) {
-  if (!closedObjectContract(type, checker)) return null;
+  if (!closedObjectContract(type, checker, true)) return null;
   const fields2 = /* @__PURE__ */ new Map();
   for (const property of type.getProperties()) {
     const declarations = property.getDeclarations();
-    if (!declarations?.length || !declarations.every((member3) => import_typescript7.default.isPropertySignature(member3) && member3.name && (import_typescript7.default.isIdentifier(member3.name) || import_typescript7.default.isStringLiteralLike(member3.name)) && member3.modifiers?.length === 1 && member3.modifiers[0]?.kind === import_typescript7.default.SyntaxKind.ReadonlyKeyword && primitiveKeyword(member3.type))) return null;
+    if (!declarations?.length || !declarations.every((member3) => import_typescript7.default.isPropertySignature(member3) && member3.name && (import_typescript7.default.isIdentifier(member3.name) || import_typescript7.default.isStringLiteralLike(member3.name)) && member3.modifiers?.length === 1 && member3.modifiers[0]?.kind === import_typescript7.default.SyntaxKind.ReadonlyKeyword && (primitiveKeyword(member3.type) || nullishPrimitiveUnion(member3.type)))) return null;
     fields2.set(property.name, (property.flags & import_typescript7.default.SymbolFlags.Optional) === 0);
   }
   return fields2.size ? fields2 : null;
 }
+function localContractBindings(roots, source, services) {
+  const pending = [...roots];
+  const visited = /* @__PURE__ */ new Set();
+  for (let index = 0; index < pending.length; index++) {
+    const node = pending[index];
+    if (!node || visited.has(node)) continue;
+    visited.add(node);
+    const references = localContractReferences(node, source, services);
+    if (references === null) return false;
+    pending.push(...references);
+  }
+  return true;
+}
+function localContractReferences(node, source, services) {
+  switch (node.type) {
+    case import_utils24.AST_NODE_TYPES.TSTypeLiteral:
+      return [];
+    case import_utils24.AST_NODE_TYPES.TSIntersectionType:
+      return node.types;
+    case import_utils24.AST_NODE_TYPES.TSTypeReference:
+      return !node.typeArguments && node.typeName.type === import_utils24.AST_NODE_TYPES.Identifier ? [node.typeName] : null;
+    case import_utils24.AST_NODE_TYPES.Identifier:
+      return localBindingReferences(node, source, services);
+    default:
+      return null;
+  }
+}
+function localBindingReferences(identifier, source, services) {
+  const definitions2 = typeBinding(source, identifier)?.defs.filter((definition) => definition.isTypeDefinition).map((definition) => definition.node);
+  if (!definitions2?.length || !definitions2.every(moduleTypeDeclaration)) return null;
+  const first = definitions2[0];
+  if (definitions2.length === 1 && first?.type === import_utils24.AST_NODE_TYPES.TSTypeAliasDeclaration && !first.typeParameters) return [first.typeAnnotation];
+  const interfaces = definitions2.filter((definition) => definition.type === import_utils24.AST_NODE_TYPES.TSInterfaceDeclaration);
+  if (interfaces.length !== definitions2.length || interfaces.some((declaration) => declaration.typeParameters)) return null;
+  if (interfaces.length > 1) {
+    const checker = services.program.getTypeChecker();
+    const symbol = checker.getSymbolAtLocation(services.esTreeNodeToTSNodeMap.get(identifier));
+    if (!symbol || interfaces.some((declaration) => checker.getSymbolAtLocation(services.esTreeNodeToTSNodeMap.get(declaration.id)) !== symbol)) return null;
+  }
+  const bases = interfaces.flatMap((declaration) => declaration.extends.map((base) => base.expression));
+  return bases.every((base) => base.type === import_utils24.AST_NODE_TYPES.Identifier) ? bases : null;
+}
+function moduleTypeDeclaration(node) {
+  const parent = node.parent;
+  if (parent?.type === import_utils24.AST_NODE_TYPES.Program) return true;
+  if (parent?.type !== import_utils24.AST_NODE_TYPES.ExportNamedDeclaration && parent?.type !== import_utils24.AST_NODE_TYPES.ExportDefaultDeclaration) return false;
+  return parent.parent.type === import_utils24.AST_NODE_TYPES.Program;
+}
+function coveringAlternative(leftNode, rightNode, checker, fieldsOf, reads) {
+  const left = checker.getTypeFromTypeNode(leftNode);
+  const right = checker.getTypeFromTypeNode(rightNode);
+  const leftFields = fieldsOf(left);
+  const rightFields = fieldsOf(right);
+  if (!leftFields || !rightFields) return null;
+  const forward = checker.isTypeAssignableTo(left, right);
+  const reverse = checker.isTypeAssignableTo(right, left);
+  const mutual = forward && reverse;
+  if (!forward && !reverse || mutual && leftFields.size === rightFields.size) return null;
+  const [covered2, covering, coveredFields, coveringFields] = forward && (!reverse || leftFields.size > rightFields.size) ? [leftNode, rightNode, leftFields, rightFields] : [rightNode, leftNode, rightFields, leftFields];
+  if ([...coveringFields.keys()].some((key) => !coveredFields.has(key)) || mutual && [...coveredFields].some(([key, required]) => required && !coveringFields.has(key)) || [...reads].some((key) => !coveringFields.has(key)) || ![...reads].some((key) => coveringFields.get(key))) return null;
+  return { covered: covered2, covering, mutual };
+}
 function privateUnionFix(sourceCode, services, proof) {
   const covering = services.tsNodeToESTreeNodeMap.get(proof.covering);
   if (!validConsumerFixCalls(proof.candidate, proof.parameter, sourceCode, services)) return null;
@@ -2787,17 +2873,11 @@ var no_redundant_consumer_union_default = createRule({
           const leftNode = annotation.types[0];
           const rightNode = annotation.types[1];
           if (!leftNode || !rightNode) continue;
-          const left = checker.getTypeFromTypeNode(leftNode);
-          const right = checker.getTypeFromTypeNode(rightNode);
-          const leftFields = fieldsOf(left);
-          const rightFields = fieldsOf(right);
-          if (!leftFields || !rightFields) continue;
-          const forward = checker.isTypeAssignableTo(left, right);
-          const reverse = checker.isTypeAssignableTo(right, left);
-          if (forward === reverse) continue;
-          const [coveredNode, coveringNode, coveredFields, coveringFields] = forward ? [leftNode, rightNode, leftFields, rightFields] : [rightNode, leftNode, rightFields, leftFields];
-          if ([...coveringFields.keys()].some((key) => !coveredFields.has(key)) || [...consumer.reads].some((key) => !coveringFields.has(key)) || ![...consumer.reads].some((key) => coveringFields.get(key))) continue;
+          const coverage = coveringAlternative(leftNode, rightNode, checker, fieldsOf, consumer.reads);
+          if (!coverage) continue;
           const reportNode = services.tsNodeToESTreeNodeMap.get(annotation);
+          if (coverage.mutual && (reportNode.type !== import_utils24.AST_NODE_TYPES.TSUnionType || !localContractBindings(reportNode.types, context.sourceCode, services))) continue;
+          const { covered: coveredNode, covering: coveringNode } = coverage;
           const fix = privateUnionFix(context.sourceCode, services, {
             candidate: candidate2,
             parameter: consumer.parameter,
@@ -2819,7 +2899,7 @@ var import_typescript8 = __toESM(require("typescript"), 1);
 var CONFIG2 = { path: "tsconfig.json", source: '{"compilerOptions":{"strict":true,"target":"ESNext","module":"ESNext","moduleResolution":"Bundler"}}' };
 var EXAMPLE2 = 'export {}; const account = {name: "Ada", email: "a"}; function label(user: {readonly email: string; readonly name: string}): string {return user.name;} label(account);';
 var HELPER_EXAMPLE = 'export {}; const account = {name: "Ada", email: "a"}; function formatName(name: string): string {return name.toUpperCase();} function label(user: {email: string; name: string}): string {return formatName(user.name);} label(account);';
-var NULLABLE_EXAMPLE = 'export {}; const account = {name: "Ada", email: null}; function label(user: {email: string | null; name: string}): string {return user.name;} label(account);';
+var NULLABLE_EXAMPLE2 = 'export {}; const account = {name: "Ada", email: null}; function label(user: {email: string | null; name: string}): string {return user.name;} label(account);';
 var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Prefer the proven read-only subset for a private consumer parameter.",
@@ -2838,8 +2918,8 @@ var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
     { id: "used-fields", title: "Every required dependency is read", outcome: "no-match", files: [{ path: "src/case.ts", source: EXAMPLE2.replace("return user.name;", "return user.name + user.email;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true },
     { id: "scalar-helper", scenarioId: "local-scalar-helper", title: "Only the name crosses a local scalar helper call", outcome: "match", files: [{ path: "src/case.ts", source: HELPER_EXAMPLE }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: HELPER_EXAMPLE.replace("email: string;", "") }] },
     { id: "helper-and-other-field", scenarioId: "local-scalar-helper", title: "The consumer still requires a separately read field", outcome: "no-match", files: [{ path: "src/case.ts", source: HELPER_EXAMPLE.replace("return formatName(user.name);", "return formatName(user.name) + user.email;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true },
-    { id: "unread-nullable-field", scenarioId: "nullable-private-field", title: "A required nullable field is never inspected", outcome: "match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("email: string | null;", "") }] },
-    { id: "read-nullable-field", scenarioId: "nullable-private-field", title: "An inspected nullable field keeps its contract", outcome: "no-match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("return user.name;", "return user.email ?? user.name;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true }
+    { id: "unread-nullable-field", scenarioId: "nullable-private-field", title: "A required nullable field is never inspected", outcome: "match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE2 }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE2.replace("email: string | null;", "") }] },
+    { id: "read-nullable-field", scenarioId: "nullable-private-field", title: "An inspected nullable field keeps its contract", outcome: "no-match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE2.replace("return user.name;", "return user.email ?? user.name;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true }
   ]
 };
 function inlineFields(node, reads) {
@@ -2853,9 +2933,6 @@ function inlineFields(node, reads) {
   }
   return fields2;
 }
-function nullishPrimitiveUnion(node) {
-  return node !== void 0 && import_typescript8.default.isUnionTypeNode(node) && node.types.length === 2 && node.types.some(primitiveKeyword) && node.types.some((part) => part.kind === import_typescript8.default.SyntaxKind.UndefinedKeyword || import_typescript8.default.isLiteralTypeNode(part) && part.literal.kind === import_typescript8.default.SyntaxKind.NullKeyword);
-}
 var prefer_minimal_parameter_contract_default = createRule({
   name: "prefer-minimal-parameter-contract",
   documentation: PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION,
@@ -4007,7 +4084,7 @@ function isSearchParamReceiver(call, services) {
 // package.json
 var package_default = {
   name: "@sarj/eslint-plugin",
-  version: "16.36.5",
+  version: "16.36.7",
   packageManager: "npm@12.2.1",
   description: "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   type: "module",

package/dist/index.js

@@ -2263,8 +2263,13 @@ function commentSuppressesChecking(text, kind) {
 
 // src/rules/_closed-object-contract.ts
 import ts2 from "typescript";
-function closedObjectContract(type, checker) {
-  return visitContract(type, { checker, active: /* @__PURE__ */ new Set(), completed: /* @__PURE__ */ new WeakMap() });
+function closedObjectContract(type, checker, singlePropertyOrigins = false) {
+  return visitContract(type, {
+    checker,
+    active: /* @__PURE__ */ new Set(),
+    completed: /* @__PURE__ */ new WeakMap(),
+    origins: singlePropertyOrigins ? /* @__PURE__ */ new Map() : void 0
+  });
 }
 function visitContract(type, proof) {
   const known2 = proof.completed.get(type);
@@ -2278,10 +2283,20 @@ function visitContract(type, proof) {
 }
 function completeObject(type, proof) {
   if (!ordinaryObject(type, proof.checker)) return false;
+  if (proof.origins && !singleOrigins(type, proof.origins)) return false;
   const declarations = type.getSymbol()?.getDeclarations()?.filter((declaration) => ts2.isInterfaceDeclaration(declaration) || ts2.isTypeLiteralNode(declaration));
   if (!declarations?.length) return false;
   return declarations.every((declaration) => completeDeclaration(declaration, proof));
 }
+function singleOrigins(type, origins) {
+  for (const property of type.getProperties()) {
+    const declarations = property.getDeclarations();
+    const declaration = declarations?.[0];
+    if (!declaration || declarations?.length !== 1 || origins.has(property.name) && origins.get(property.name) !== declaration) return false;
+    origins.set(property.name, declaration);
+  }
+  return true;
+}
 function ordinaryObject(type, checker) {
   if ((type.flags & ts2.TypeFlags.Object) === 0 || type.isUnion() || checker.getIndexInfosOfType(type).length > 0) return false;
   const object = type;
@@ -2600,6 +2615,9 @@ function directEval(node) {
 function primitiveKeyword(node) {
   return node !== void 0 && (node.kind === ts6.SyntaxKind.StringKeyword || node.kind === ts6.SyntaxKind.NumberKeyword || node.kind === ts6.SyntaxKind.BooleanKeyword || node.kind === ts6.SyntaxKind.BigIntKeyword);
 }
+function nullishPrimitiveUnion(node) {
+  return node !== void 0 && ts6.isUnionTypeNode(node) && node.types.length === 2 && node.types.some(primitiveKeyword) && node.types.some((part) => part.kind === ts6.SyntaxKind.UndefinedKeyword || ts6.isLiteralTypeNode(part) && part.literal.kind === ts6.SyntaxKind.NullKeyword);
+}
 function consumerAnnotation(node) {
   if (node.params.length !== 1) return void 0;
   const parameter = node.params[0];
@@ -2657,6 +2675,8 @@ function directCalls(binding3) {
 // src/rules/no-redundant-consumer-union.ts
 var CONFIG = { path: "tsconfig.json", source: '{"compilerOptions":{"strict":true,"target":"ESNext","module":"ESNext","moduleResolution":"Bundler"}}' };
 var EXAMPLE = 'export {}; interface Animal {readonly name: string} interface Dog extends Animal {readonly breed: string} export type KeptDog = Dog; const dog: Dog = {name: "Ada", breed: "Collie"}; function label(value: Dog | Animal): string {return value.name;} label(dog);';
+var NULLABLE_EXAMPLE = EXAMPLE.replace("readonly name: string", "readonly name: string | null").replace("return value.name;", "return value.name ?? '';");
+var OPTIONAL_EXAMPLE = EXAMPLE.replace("readonly breed: string", "readonly breed?: string");
 var NO_REDUNDANT_CONSUMER_UNION_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Keep the covering object contract in a private scalar consumer union.",
@@ -2667,25 +2687,91 @@ var NO_REDUNDANT_CONSUMER_UNION_DOCUMENTATION = {
   limitations: [
     "Automatic fixes additionally require every existing identifier caller to be natively assignable to the original contract, without Any, unknown, error or unresolved types on the relevant surface. Comments inside the annotation and TypeScript suppression directives keep the finding manual. Removed named types/imports must retain an independent top-level exported type-alias or direct type-export read. Other removable annotations/assertions, the covering annotation and own-definition/self references cannot keep one another live; otherwise simultaneous fixes can introduce unused-type errors. The exact authored covering type and terminator token sequence are retained; edits that would merge distinct CR and LF terminators remain manual; no producer, call or function body is rewritten.",
     "Only an inline binary parameter union in a strict module's top-level private scalar consumer is supported. Exactly one parameter, an explicit broad primitive return annotation, a single pure returned scalar expression and direct identifier-argument callers are required. Type queries or type-only exports of the callable, public APIs, callbacks, contextual signatures, overloads, generics, decorators, async functions, direct eval and fresh-object callers prevent findings.",
-    "Both alternatives must have complete ordinary finite structural surfaces consisting only of explicitly readonly broad string, number, boolean or bigint properties. Aliases, imports, re-exports and ordinary inheritance are resolved by the parser-owned TypeScript checker. Any, unknown, missing imports, open/generic/mapped/indexed types, classes, brands, literal discriminants, methods, properties with scalar type aliases, callbacks and recursive or nested object fields are unsupported.",
-    "Reports only proper native assignability: covered is assignable to covering and the reverse is false. Every covering member, including optional members, must exist in the covered type's enumerated declared surface. Otherwise an existing identifier may carry an incompatible extra field and be rejected after simplification; implicit Object members containing Any also cannot witness coverage. The covering type must declare every read field and a read required field; an all-optional reduced contract can reject existing callers. Identical alternatives and primitive/top/bottom redundancy remain upstream-owned; mutually assignable but nonidentical structures are excluded.",
+    "Both alternatives must have complete ordinary finite structural surfaces consisting only of explicitly readonly broad string, number, boolean or bigint properties, optionally paired directly with null or undefined in an exact two-part union. Required and optional nullable fields may be read under the same native coverage proof. Every field must have one actual declaration origin throughout each alternative's inheritance/intersection graph. Shared ancestors retain that origin; repeated merged fields, explicit overrides and independently declared overlapping fields abstain, including valid compatible declarations. This excludes recovered conflicting properties without claiming whole-source health. Aliases, imports, re-exports and ordinary inheritance are resolved by the parser-owned TypeScript checker. Any, unknown, missing imports, open/generic/mapped/indexed types, classes, brands, literal discriminants, methods, properties with scalar type aliases, parenthesized or more complex property unions, callbacks and recursive or nested object fields are unsupported.",
+    "Reports proper native assignability, where covered is assignable to covering and the reverse is false, or mutual native assignability with a strict smaller declared covering surface and only optional covered-only members. Every covering member, including optional members, must exist in the covered type's enumerated declared surface. Otherwise an existing identifier may carry an incompatible extra field and be rejected after simplification; implicit Object members containing Any cannot replace explicit declared coverage or the native Optional requirement. The covering type must declare every read field and a read required field; an all-optional reduced contract can reject existing callers. Identical alternatives and primitive/top/bottom redundancy remain upstream-owned; equal-key and incomparable mutually assignable structures are excluded. The mutual case additionally requires inline contracts or locally bound interfaces/type aliases whose alias and heritage references can be traced through the parser-owned type scope. Merged interface fragments must all resolve to the reference's same native symbol; mixed exported/local recovery abstains. Imported, global and qualified-namespace references in that path abstain; proper one-way coverage retains its existing alias/import support.",
     "General union simplification can change Extract, conditional types, in-narrowing, fresh-literal checking and public presentation. Those contexts are excluded even when ordinary assignment succeeds. Flat destructuring counts every bound field as read; whole-object escape, mutation, helpers, closures, reflection, serialization, dynamic reads, implicit Object capabilities and JSX prevent findings. Imported Python protocol assignability is not approximated by this rule."
   ],
   examples: [
     { id: "covered-alternative", title: "The private consumer needs the covering Animal contract", outcome: "match", files: [{ path: "src/case.ts", source: EXAMPLE }, CONFIG], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: EXAMPLE.replace("Dog | Animal", "Animal") }] },
-    { id: "public-contract", title: "A public union retains its observable alternatives", outcome: "no-match", files: [{ path: "src/case.ts", source: EXAMPLE.replace("function label", "export function label") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true }
+    { id: "public-contract", title: "A public union retains its observable alternatives", outcome: "no-match", files: [{ path: "src/case.ts", source: EXAMPLE.replace("function label", "export function label") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true },
+    { id: "optional-covered-alternative", scenarioId: "optional-readonly-contract", title: "An unread optional breed retains the smaller Animal surface", outcome: "match", files: [{ path: "src/case.ts", source: OPTIONAL_EXAMPLE }, CONFIG], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: OPTIONAL_EXAMPLE.replace("Dog | Animal", "Animal") }] },
+    { id: "optional-public-contract", scenarioId: "optional-readonly-contract", title: "A public optional union retains its observable alternatives", outcome: "no-match", files: [{ path: "src/case.ts", source: OPTIONAL_EXAMPLE.replace("function label", "export function label") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true },
+    { id: "nullable-covered-alternative", scenarioId: "nullable-readonly-contract", title: "A nullable name retains the covering Animal contract", outcome: "match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE }, CONFIG], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("Dog | Animal", "Animal") }] },
+    { id: "nullable-domain-contract", scenarioId: "nullable-readonly-contract", title: "A literal breed keeps the authored domain contract", outcome: "no-match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("readonly breed: string", "readonly breed: 'Collie'") }, CONFIG], focusPath: "src/case.ts", expectedCount: 0, public: true }
   ]
 };
 function scalarFields(type, checker) {
-  if (!closedObjectContract(type, checker)) return null;
+  if (!closedObjectContract(type, checker, true)) return null;
   const fields2 = /* @__PURE__ */ new Map();
   for (const property of type.getProperties()) {
     const declarations = property.getDeclarations();
-    if (!declarations?.length || !declarations.every((member3) => ts7.isPropertySignature(member3) && member3.name && (ts7.isIdentifier(member3.name) || ts7.isStringLiteralLike(member3.name)) && member3.modifiers?.length === 1 && member3.modifiers[0]?.kind === ts7.SyntaxKind.ReadonlyKeyword && primitiveKeyword(member3.type))) return null;
+    if (!declarations?.length || !declarations.every((member3) => ts7.isPropertySignature(member3) && member3.name && (ts7.isIdentifier(member3.name) || ts7.isStringLiteralLike(member3.name)) && member3.modifiers?.length === 1 && member3.modifiers[0]?.kind === ts7.SyntaxKind.ReadonlyKeyword && (primitiveKeyword(member3.type) || nullishPrimitiveUnion(member3.type)))) return null;
     fields2.set(property.name, (property.flags & ts7.SymbolFlags.Optional) === 0);
   }
   return fields2.size ? fields2 : null;
 }
+function localContractBindings(roots, source, services) {
+  const pending = [...roots];
+  const visited = /* @__PURE__ */ new Set();
+  for (let index = 0; index < pending.length; index++) {
+    const node = pending[index];
+    if (!node || visited.has(node)) continue;
+    visited.add(node);
+    const references = localContractReferences(node, source, services);
+    if (references === null) return false;
+    pending.push(...references);
+  }
+  return true;
+}
+function localContractReferences(node, source, services) {
+  switch (node.type) {
+    case AST_NODE_TYPES22.TSTypeLiteral:
+      return [];
+    case AST_NODE_TYPES22.TSIntersectionType:
+      return node.types;
+    case AST_NODE_TYPES22.TSTypeReference:
+      return !node.typeArguments && node.typeName.type === AST_NODE_TYPES22.Identifier ? [node.typeName] : null;
+    case AST_NODE_TYPES22.Identifier:
+      return localBindingReferences(node, source, services);
+    default:
+      return null;
+  }
+}
+function localBindingReferences(identifier, source, services) {
+  const definitions2 = typeBinding(source, identifier)?.defs.filter((definition) => definition.isTypeDefinition).map((definition) => definition.node);
+  if (!definitions2?.length || !definitions2.every(moduleTypeDeclaration)) return null;
+  const first = definitions2[0];
+  if (definitions2.length === 1 && first?.type === AST_NODE_TYPES22.TSTypeAliasDeclaration && !first.typeParameters) return [first.typeAnnotation];
+  const interfaces = definitions2.filter((definition) => definition.type === AST_NODE_TYPES22.TSInterfaceDeclaration);
+  if (interfaces.length !== definitions2.length || interfaces.some((declaration) => declaration.typeParameters)) return null;
+  if (interfaces.length > 1) {
+    const checker = services.program.getTypeChecker();
+    const symbol = checker.getSymbolAtLocation(services.esTreeNodeToTSNodeMap.get(identifier));
+    if (!symbol || interfaces.some((declaration) => checker.getSymbolAtLocation(services.esTreeNodeToTSNodeMap.get(declaration.id)) !== symbol)) return null;
+  }
+  const bases = interfaces.flatMap((declaration) => declaration.extends.map((base) => base.expression));
+  return bases.every((base) => base.type === AST_NODE_TYPES22.Identifier) ? bases : null;
+}
+function moduleTypeDeclaration(node) {
+  const parent = node.parent;
+  if (parent?.type === AST_NODE_TYPES22.Program) return true;
+  if (parent?.type !== AST_NODE_TYPES22.ExportNamedDeclaration && parent?.type !== AST_NODE_TYPES22.ExportDefaultDeclaration) return false;
+  return parent.parent.type === AST_NODE_TYPES22.Program;
+}
+function coveringAlternative(leftNode, rightNode, checker, fieldsOf, reads) {
+  const left = checker.getTypeFromTypeNode(leftNode);
+  const right = checker.getTypeFromTypeNode(rightNode);
+  const leftFields = fieldsOf(left);
+  const rightFields = fieldsOf(right);
+  if (!leftFields || !rightFields) return null;
+  const forward = checker.isTypeAssignableTo(left, right);
+  const reverse = checker.isTypeAssignableTo(right, left);
+  const mutual = forward && reverse;
+  if (!forward && !reverse || mutual && leftFields.size === rightFields.size) return null;
+  const [covered2, covering, coveredFields, coveringFields] = forward && (!reverse || leftFields.size > rightFields.size) ? [leftNode, rightNode, leftFields, rightFields] : [rightNode, leftNode, rightFields, leftFields];
+  if ([...coveringFields.keys()].some((key) => !coveredFields.has(key)) || mutual && [...coveredFields].some(([key, required]) => required && !coveringFields.has(key)) || [...reads].some((key) => !coveringFields.has(key)) || ![...reads].some((key) => coveringFields.get(key))) return null;
+  return { covered: covered2, covering, mutual };
+}
 function privateUnionFix(sourceCode, services, proof) {
   const covering = services.tsNodeToESTreeNodeMap.get(proof.covering);
   if (!validConsumerFixCalls(proof.candidate, proof.parameter, sourceCode, services)) return null;
@@ -2736,17 +2822,11 @@ var no_redundant_consumer_union_default = createRule({
           const leftNode = annotation.types[0];
           const rightNode = annotation.types[1];
           if (!leftNode || !rightNode) continue;
-          const left = checker.getTypeFromTypeNode(leftNode);
-          const right = checker.getTypeFromTypeNode(rightNode);
-          const leftFields = fieldsOf(left);
-          const rightFields = fieldsOf(right);
-          if (!leftFields || !rightFields) continue;
-          const forward = checker.isTypeAssignableTo(left, right);
-          const reverse = checker.isTypeAssignableTo(right, left);
-          if (forward === reverse) continue;
-          const [coveredNode, coveringNode, coveredFields, coveringFields] = forward ? [leftNode, rightNode, leftFields, rightFields] : [rightNode, leftNode, rightFields, leftFields];
-          if ([...coveringFields.keys()].some((key) => !coveredFields.has(key)) || [...consumer.reads].some((key) => !coveringFields.has(key)) || ![...consumer.reads].some((key) => coveringFields.get(key))) continue;
+          const coverage = coveringAlternative(leftNode, rightNode, checker, fieldsOf, consumer.reads);
+          if (!coverage) continue;
           const reportNode = services.tsNodeToESTreeNodeMap.get(annotation);
+          if (coverage.mutual && (reportNode.type !== AST_NODE_TYPES22.TSUnionType || !localContractBindings(reportNode.types, context.sourceCode, services))) continue;
+          const { covered: coveredNode, covering: coveringNode } = coverage;
           const fix = privateUnionFix(context.sourceCode, services, {
             candidate: candidate2,
             parameter: consumer.parameter,
@@ -2768,7 +2848,7 @@ import ts8 from "typescript";
 var CONFIG2 = { path: "tsconfig.json", source: '{"compilerOptions":{"strict":true,"target":"ESNext","module":"ESNext","moduleResolution":"Bundler"}}' };
 var EXAMPLE2 = 'export {}; const account = {name: "Ada", email: "a"}; function label(user: {readonly email: string; readonly name: string}): string {return user.name;} label(account);';
 var HELPER_EXAMPLE = 'export {}; const account = {name: "Ada", email: "a"}; function formatName(name: string): string {return name.toUpperCase();} function label(user: {email: string; name: string}): string {return formatName(user.name);} label(account);';
-var NULLABLE_EXAMPLE = 'export {}; const account = {name: "Ada", email: null}; function label(user: {email: string | null; name: string}): string {return user.name;} label(account);';
+var NULLABLE_EXAMPLE2 = 'export {}; const account = {name: "Ada", email: null}; function label(user: {email: string | null; name: string}): string {return user.name;} label(account);';
 var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Prefer the proven read-only subset for a private consumer parameter.",
@@ -2787,8 +2867,8 @@ var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
     { id: "used-fields", title: "Every required dependency is read", outcome: "no-match", files: [{ path: "src/case.ts", source: EXAMPLE2.replace("return user.name;", "return user.name + user.email;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true },
     { id: "scalar-helper", scenarioId: "local-scalar-helper", title: "Only the name crosses a local scalar helper call", outcome: "match", files: [{ path: "src/case.ts", source: HELPER_EXAMPLE }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: HELPER_EXAMPLE.replace("email: string;", "") }] },
     { id: "helper-and-other-field", scenarioId: "local-scalar-helper", title: "The consumer still requires a separately read field", outcome: "no-match", files: [{ path: "src/case.ts", source: HELPER_EXAMPLE.replace("return formatName(user.name);", "return formatName(user.name) + user.email;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true },
-    { id: "unread-nullable-field", scenarioId: "nullable-private-field", title: "A required nullable field is never inspected", outcome: "match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("email: string | null;", "") }] },
-    { id: "read-nullable-field", scenarioId: "nullable-private-field", title: "An inspected nullable field keeps its contract", outcome: "no-match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE.replace("return user.name;", "return user.email ?? user.name;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true }
+    { id: "unread-nullable-field", scenarioId: "nullable-private-field", title: "A required nullable field is never inspected", outcome: "match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE2 }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE2.replace("email: string | null;", "") }] },
+    { id: "read-nullable-field", scenarioId: "nullable-private-field", title: "An inspected nullable field keeps its contract", outcome: "no-match", files: [{ path: "src/case.ts", source: NULLABLE_EXAMPLE2.replace("return user.name;", "return user.email ?? user.name;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true }
   ]
 };
 function inlineFields(node, reads) {
@@ -2802,9 +2882,6 @@ function inlineFields(node, reads) {
   }
   return fields2;
 }
-function nullishPrimitiveUnion(node) {
-  return node !== void 0 && ts8.isUnionTypeNode(node) && node.types.length === 2 && node.types.some(primitiveKeyword) && node.types.some((part) => part.kind === ts8.SyntaxKind.UndefinedKeyword || ts8.isLiteralTypeNode(part) && part.literal.kind === ts8.SyntaxKind.NullKeyword);
-}
 var prefer_minimal_parameter_contract_default = createRule({
   name: "prefer-minimal-parameter-contract",
   documentation: PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION,
@@ -3960,7 +4037,7 @@ function isSearchParamReceiver(call, services) {
 // package.json
 var package_default = {
   name: "@sarj/eslint-plugin",
-  version: "16.36.5",
+  version: "16.36.7",
   packageManager: "npm@12.2.1",
   description: "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   type: "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "16.36.5",
+  "version": "16.36.7",
   "packageManager": "npm@12.2.1",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",