@sarj/eslint-plugin 16.38.50 → 16.38.53

package/dist/index.cjs

@@ -2573,16 +2573,68 @@ function typeBinding(source, identifier) {
   }
   return null;
 }
+var REFERENCE_INDEXES = /* @__PURE__ */ new WeakMap();
 function retainsNamedTypeUses(source, removed) {
   const manager = source.scopeManager;
   if (manager === null) return false;
-  const references = manager.scopes.flatMap((scope) => scope.references).filter((reference) => reference.isRead() && insideTypeRange(reference.identifier, removed));
-  return references.every((reference) => {
+  const index = referenceIndex(source, manager);
+  for (const reference of referencesWithin(index.references, removed)) {
+    if (!reference.isRead()) continue;
     const binding3 = reference.resolved;
     if (!binding3 || !reference.isTypeReference && !reference.isValueReference) return false;
-    if (binding3.defs.length === 0) return true;
-    return binding3.references.some((retained) => retained.isRead() && (!reference.isTypeReference || retained.isTypeReference) && (!reference.isValueReference || retained.isValueReference) && !insideTypeRange(retained.identifier, removed) && !binding3.defs.some((definition) => insideTypeRange(retained.identifier, definition.node)) && publicTypeUse(retained.identifier));
-  });
+    if (binding3.defs.length === 0) continue;
+    const reads = publicReadExtents(index, binding3);
+    const extent = reference.isTypeReference ? reference.isValueReference ? reads.both : reads.type : reads.value;
+    if (extent === null || extent.minStart >= removed.range[0] && extent.maxEnd <= removed.range[1]) return false;
+  }
+  return true;
+}
+function referenceIndex(source, manager) {
+  const cached = REFERENCE_INDEXES.get(source);
+  if (cached?.manager === manager) return cached;
+  const references = manager.scopes.flatMap((scope) => scope.references);
+  references.sort((left, right) => left.identifier.range[0] - right.identifier.range[0]);
+  const index = { manager, references, publicReads: /* @__PURE__ */ new Map() };
+  REFERENCE_INDEXES.set(source, index);
+  return index;
+}
+function* referencesWithin(references, removed) {
+  let low = 0;
+  let high = references.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    const reference = references[middle];
+    if (reference === void 0 || reference.identifier.range[0] >= removed.range[0]) high = middle;
+    else low = middle + 1;
+  }
+  for (let index = low; index < references.length; index++) {
+    const reference = references[index];
+    if (reference === void 0) continue;
+    if (reference.identifier.range[0] > removed.range[1]) break;
+    if (insideTypeRange(reference.identifier, removed)) yield reference;
+  }
+}
+function publicReadExtents(index, binding3) {
+  const cached = index.publicReads.get(binding3);
+  if (cached !== void 0) return cached;
+  let type = null;
+  let value = null;
+  let both = null;
+  for (const retained of binding3.references) {
+    if (!retained.isRead() || !retained.isTypeReference && !retained.isValueReference || binding3.defs.some((definition) => insideTypeRange(retained.identifier, definition.node)) || !publicTypeUse(retained.identifier)) continue;
+    if (retained.isTypeReference) type = extendExtent(type, retained.identifier);
+    if (retained.isValueReference) value = extendExtent(value, retained.identifier);
+    if (retained.isTypeReference && retained.isValueReference) both = extendExtent(both, retained.identifier);
+  }
+  const result = { type, value, both };
+  index.publicReads.set(binding3, result);
+  return result;
+}
+function extendExtent(extent, identifier) {
+  return {
+    minStart: Math.min(extent?.minStart ?? identifier.range[0], identifier.range[0]),
+    maxEnd: Math.max(extent?.maxEnd ?? identifier.range[1], identifier.range[1])
+  };
 }
 function publicTypeUse(identifier) {
   let node = identifier;
@@ -3069,6 +3121,7 @@ var CONFIG2 = { path: "tsconfig.json", source: '{"compilerOptions":{"strict":tru
 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_EXAMPLE2 = 'export {}; const account = {name: "Ada", email: null}; function label(user: {email: string | null; name: string}): string {return user.name;} label(account);';
+var READ_NULLABLE_EXAMPLE = EXAMPLE2.replace('name: "Ada"', "name: null").replace("readonly name: string", "readonly name: string | null").replace("return user.name;", 'return user.name ?? "";');
 var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Prefer the proven read-only subset for a private consumer parameter.",
@@ -3079,7 +3132,7 @@ var PREFER_MINIMAL_PARAMETER_CONTRACT_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. Only unread required property signatures are removed; every read or optional member, modifier and terminator token is preserved. Edits that would merge distinct CR and LF terminators remain manual.",
     "Requires parser-owned TypeScript information and a strict external module. Only top-level private function declarations and raw const arrows with exactly one explicit parameter and an independent broad primitive return annotation are supported. Every callable reference must be a direct call with one identifier argument; exports including type-only exports, typeof queries, callbacks, storage, constructors, contextual signatures, overloads, generics, decorators, async functions and direct eval prevent findings.",
-    "Only anonymous inline contracts made of broad string, number, boolean or bigint property types are supported. An unread required field may additionally have exactly one such keyword and null or undefined in a direct two-part union; read or optional nullable fields and more complex unions remain excluded. Fields may be plain or readonly; the consumer body must still prove read-only usage. Retained field modifiers and optional members are preserved. Named domain contracts, brands, literal discriminants, classes, methods, callbacks, indexes, mapped types and imported parameter contracts are excluded. At least one read required field and one unread required field must be established; all-optional reduced contracts can reject existing callers through weak-type checks.",
+    "Only anonymous inline contracts made of broad string, number, boolean or bigint property types are supported. A read field or an unread required field may additionally have exactly one such keyword and null or undefined in a direct two-part union; unread optional nullable fields and more complex unions remain excluded. Fields may be plain or readonly; the consumer body must still prove read-only usage. Every read field keeps its exact type, modifiers and optionality. Named domain contracts, brands, literal discriminants, classes, methods, callbacks, indexes, mapped types and imported parameter contracts are excluded. At least one read required field and one unread required field must be established; all-optional reduced contracts can reject existing callers through weak-type checks.",
     "The single return expression may use only fixed scalar field reads, flat destructuring, literals, operators, templates and scalar calls to same-file implemented top-level functions or raw const arrows with an explicit return annotation. These calls require one native resolved declaration, no generic or predicate signature, scalar arguments/result and complete active native checking of the local implementation file. Their helper bodies need not be pure because only scalar values cross the call and only an erased parameter annotation changes. Imported, aliased, ambient, overloaded, optional, spread and member calls remain unsupported. Bound destructured fields count as reads even when their local aliases are unused. Whole-object escape, identity, mutation, closures, reflection, serialization, dynamic keys, implicit Object capabilities and JSX are unsupported. Unknown semantic information causes abstention. Findings outside the fix proof remain manual; this is not a requirement to minimize every object or discard useful producer fields."
   ],
   examples: [
@@ -3088,7 +3141,9 @@ var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
     { 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_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 }
+    { 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 },
+    { id: "retained-nullable-read", scenarioId: "retained-nullable-field", title: "A nullable name remains while an unread email requirement is removed", outcome: "match", files: [{ path: "src/case.ts", source: READ_NULLABLE_EXAMPLE }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: READ_NULLABLE_EXAMPLE.replace("readonly email: string;", "") }] },
+    { id: "retained-nullable-all-used", scenarioId: "retained-nullable-field", title: "Both requirements remain when the nullable view reads email too", outcome: "no-match", files: [{ path: "src/case.ts", source: READ_NULLABLE_EXAMPLE.replace('return user.name ?? "";', "return user.name ?? user.email;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true }
   ]
 };
 function inlineFields(node, reads) {
@@ -3096,7 +3151,7 @@ function inlineFields(node, reads) {
   for (const member3 of node.members) {
     if (!import_typescript8.default.isPropertySignature(member3) || !member3.name || !import_typescript8.default.isIdentifier(member3.name) && !import_typescript8.default.isStringLiteralLike(member3.name) || (member3.modifiers?.length ?? 0) > 1 || member3.modifiers?.some((modifier) => modifier.kind !== import_typescript8.default.SyntaxKind.ReadonlyKeyword)) return null;
     const key = member3.name.text;
-    if (!primitiveKeyword(member3.type) && (member3.questionToken || reads.has(key) || !nullishPrimitiveUnion(member3.type))) return null;
+    if (!primitiveKeyword(member3.type) && (!nullishPrimitiveUnion(member3.type) || member3.questionToken && !reads.has(key))) return null;
     if (fields2.has(key)) return null;
     fields2.set(key, !member3.questionToken);
   }
@@ -4209,7 +4264,7 @@ function isSearchParamReceiver(call, services) {
 // package.json
 var package_default = {
   name: "@sarj/eslint-plugin",
-  version: "16.38.50",
+  version: "16.38.53",
   packageManager: "npm@12.2.1",
   description: "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   type: "module",

package/dist/index.js

@@ -2522,16 +2522,68 @@ function typeBinding(source, identifier) {
   }
   return null;
 }
+var REFERENCE_INDEXES = /* @__PURE__ */ new WeakMap();
 function retainsNamedTypeUses(source, removed) {
   const manager = source.scopeManager;
   if (manager === null) return false;
-  const references = manager.scopes.flatMap((scope) => scope.references).filter((reference) => reference.isRead() && insideTypeRange(reference.identifier, removed));
-  return references.every((reference) => {
+  const index = referenceIndex(source, manager);
+  for (const reference of referencesWithin(index.references, removed)) {
+    if (!reference.isRead()) continue;
     const binding3 = reference.resolved;
     if (!binding3 || !reference.isTypeReference && !reference.isValueReference) return false;
-    if (binding3.defs.length === 0) return true;
-    return binding3.references.some((retained) => retained.isRead() && (!reference.isTypeReference || retained.isTypeReference) && (!reference.isValueReference || retained.isValueReference) && !insideTypeRange(retained.identifier, removed) && !binding3.defs.some((definition) => insideTypeRange(retained.identifier, definition.node)) && publicTypeUse(retained.identifier));
-  });
+    if (binding3.defs.length === 0) continue;
+    const reads = publicReadExtents(index, binding3);
+    const extent = reference.isTypeReference ? reference.isValueReference ? reads.both : reads.type : reads.value;
+    if (extent === null || extent.minStart >= removed.range[0] && extent.maxEnd <= removed.range[1]) return false;
+  }
+  return true;
+}
+function referenceIndex(source, manager) {
+  const cached = REFERENCE_INDEXES.get(source);
+  if (cached?.manager === manager) return cached;
+  const references = manager.scopes.flatMap((scope) => scope.references);
+  references.sort((left, right) => left.identifier.range[0] - right.identifier.range[0]);
+  const index = { manager, references, publicReads: /* @__PURE__ */ new Map() };
+  REFERENCE_INDEXES.set(source, index);
+  return index;
+}
+function* referencesWithin(references, removed) {
+  let low = 0;
+  let high = references.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    const reference = references[middle];
+    if (reference === void 0 || reference.identifier.range[0] >= removed.range[0]) high = middle;
+    else low = middle + 1;
+  }
+  for (let index = low; index < references.length; index++) {
+    const reference = references[index];
+    if (reference === void 0) continue;
+    if (reference.identifier.range[0] > removed.range[1]) break;
+    if (insideTypeRange(reference.identifier, removed)) yield reference;
+  }
+}
+function publicReadExtents(index, binding3) {
+  const cached = index.publicReads.get(binding3);
+  if (cached !== void 0) return cached;
+  let type = null;
+  let value = null;
+  let both = null;
+  for (const retained of binding3.references) {
+    if (!retained.isRead() || !retained.isTypeReference && !retained.isValueReference || binding3.defs.some((definition) => insideTypeRange(retained.identifier, definition.node)) || !publicTypeUse(retained.identifier)) continue;
+    if (retained.isTypeReference) type = extendExtent(type, retained.identifier);
+    if (retained.isValueReference) value = extendExtent(value, retained.identifier);
+    if (retained.isTypeReference && retained.isValueReference) both = extendExtent(both, retained.identifier);
+  }
+  const result = { type, value, both };
+  index.publicReads.set(binding3, result);
+  return result;
+}
+function extendExtent(extent, identifier) {
+  return {
+    minStart: Math.min(extent?.minStart ?? identifier.range[0], identifier.range[0]),
+    maxEnd: Math.max(extent?.maxEnd ?? identifier.range[1], identifier.range[1])
+  };
 }
 function publicTypeUse(identifier) {
   let node = identifier;
@@ -3018,6 +3070,7 @@ var CONFIG2 = { path: "tsconfig.json", source: '{"compilerOptions":{"strict":tru
 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_EXAMPLE2 = 'export {}; const account = {name: "Ada", email: null}; function label(user: {email: string | null; name: string}): string {return user.name;} label(account);';
+var READ_NULLABLE_EXAMPLE = EXAMPLE2.replace('name: "Ada"', "name: null").replace("readonly name: string", "readonly name: string | null").replace("return user.name;", 'return user.name ?? "";');
 var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Prefer the proven read-only subset for a private consumer parameter.",
@@ -3028,7 +3081,7 @@ var PREFER_MINIMAL_PARAMETER_CONTRACT_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. Only unread required property signatures are removed; every read or optional member, modifier and terminator token is preserved. Edits that would merge distinct CR and LF terminators remain manual.",
     "Requires parser-owned TypeScript information and a strict external module. Only top-level private function declarations and raw const arrows with exactly one explicit parameter and an independent broad primitive return annotation are supported. Every callable reference must be a direct call with one identifier argument; exports including type-only exports, typeof queries, callbacks, storage, constructors, contextual signatures, overloads, generics, decorators, async functions and direct eval prevent findings.",
-    "Only anonymous inline contracts made of broad string, number, boolean or bigint property types are supported. An unread required field may additionally have exactly one such keyword and null or undefined in a direct two-part union; read or optional nullable fields and more complex unions remain excluded. Fields may be plain or readonly; the consumer body must still prove read-only usage. Retained field modifiers and optional members are preserved. Named domain contracts, brands, literal discriminants, classes, methods, callbacks, indexes, mapped types and imported parameter contracts are excluded. At least one read required field and one unread required field must be established; all-optional reduced contracts can reject existing callers through weak-type checks.",
+    "Only anonymous inline contracts made of broad string, number, boolean or bigint property types are supported. A read field or an unread required field may additionally have exactly one such keyword and null or undefined in a direct two-part union; unread optional nullable fields and more complex unions remain excluded. Fields may be plain or readonly; the consumer body must still prove read-only usage. Every read field keeps its exact type, modifiers and optionality. Named domain contracts, brands, literal discriminants, classes, methods, callbacks, indexes, mapped types and imported parameter contracts are excluded. At least one read required field and one unread required field must be established; all-optional reduced contracts can reject existing callers through weak-type checks.",
     "The single return expression may use only fixed scalar field reads, flat destructuring, literals, operators, templates and scalar calls to same-file implemented top-level functions or raw const arrows with an explicit return annotation. These calls require one native resolved declaration, no generic or predicate signature, scalar arguments/result and complete active native checking of the local implementation file. Their helper bodies need not be pure because only scalar values cross the call and only an erased parameter annotation changes. Imported, aliased, ambient, overloaded, optional, spread and member calls remain unsupported. Bound destructured fields count as reads even when their local aliases are unused. Whole-object escape, identity, mutation, closures, reflection, serialization, dynamic keys, implicit Object capabilities and JSX are unsupported. Unknown semantic information causes abstention. Findings outside the fix proof remain manual; this is not a requirement to minimize every object or discard useful producer fields."
   ],
   examples: [
@@ -3037,7 +3090,9 @@ var PREFER_MINIMAL_PARAMETER_CONTRACT_DOCUMENTATION = {
     { 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_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 }
+    { 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 },
+    { id: "retained-nullable-read", scenarioId: "retained-nullable-field", title: "A nullable name remains while an unread email requirement is removed", outcome: "match", files: [{ path: "src/case.ts", source: READ_NULLABLE_EXAMPLE }, CONFIG2], focusPath: "src/case.ts", expectedCount: 1, public: true, fixedFiles: [{ path: "src/case.ts", source: READ_NULLABLE_EXAMPLE.replace("readonly email: string;", "") }] },
+    { id: "retained-nullable-all-used", scenarioId: "retained-nullable-field", title: "Both requirements remain when the nullable view reads email too", outcome: "no-match", files: [{ path: "src/case.ts", source: READ_NULLABLE_EXAMPLE.replace('return user.name ?? "";', "return user.name ?? user.email;") }, CONFIG2], focusPath: "src/case.ts", expectedCount: 0, public: true }
   ]
 };
 function inlineFields(node, reads) {
@@ -3045,7 +3100,7 @@ function inlineFields(node, reads) {
   for (const member3 of node.members) {
     if (!ts8.isPropertySignature(member3) || !member3.name || !ts8.isIdentifier(member3.name) && !ts8.isStringLiteralLike(member3.name) || (member3.modifiers?.length ?? 0) > 1 || member3.modifiers?.some((modifier) => modifier.kind !== ts8.SyntaxKind.ReadonlyKeyword)) return null;
     const key = member3.name.text;
-    if (!primitiveKeyword(member3.type) && (member3.questionToken || reads.has(key) || !nullishPrimitiveUnion(member3.type))) return null;
+    if (!primitiveKeyword(member3.type) && (!nullishPrimitiveUnion(member3.type) || member3.questionToken && !reads.has(key))) return null;
     if (fields2.has(key)) return null;
     fields2.set(key, !member3.questionToken);
   }
@@ -4162,7 +4217,7 @@ function isSearchParamReceiver(call, services) {
 // package.json
 var package_default = {
   name: "@sarj/eslint-plugin",
-  version: "16.38.50",
+  version: "16.38.53",
   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.38.50",
+  "version": "16.38.53",
   "packageManager": "npm@12.2.1",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",