@sarj/eslint-plugin 19.17.0 → 19.18.0

package/dist/catalog.js

@@ -2,7 +2,7 @@ import {
   publicDocumentation,
   ruleSpec,
   src_default
-} from "./chunk-4USNCXB3.js";
+} from "./chunk-E2O4LN7G.js";
 
 // src/docs/directive-disable-enable-pair.ts
 var DIRECTIVE_DISABLE_ENABLE_PAIR_DOCUMENTATION = {
@@ -5118,11 +5118,13 @@ var PREFER_DISCRIMINATED_UNION_DOCUMENTATION = {
   summary: "Preserve producer-proven tag/payload and Boolean state relationships in return types.",
   defaultLevel: "warning",
   rationale: "A flat object with optional branch data loses the relationship between a tag and its payload. Callers cannot narrow to the required fields, and the type permits incomplete or contradictory combinations.",
-  remediation: "If the variants are mutually exclusive, represent each with a literal tag and its required payload. Preserve shared fields on every member, including payload value types and nullability. For a producer returning a subset of a broader wire contract, give the producer a precise domain return type after validation.",
+  remediation: "If the variants are mutually exclusive, represent each with a literal tag and its required payload. For predicates over one current state, consider returning that authoritative state instead of storing multiple derived flags. Preserve every valid state, independent dimension, shared field, payload value type and nullability. For a producer returning a subset of a broader wire contract, give the producer a precise domain return type after validation.",
   category: "correctness",
   autofix: "safe",
   limitations: [
-    "Names, Boolean counts and optional-field counts never establish a finding. A producer's literal writes establish either tag-specific payload presence or a pair of required Boolean fields with two or three distinct combinations, with both fields varying. Boolean members may use boolean, true | false or one unmerged nongeneric local alias of either. All four combinations, constant dimensions, optional/unknown dimensions and expression-valued flags are excluded. At most eight Boolean fields are compared. Only one relationship is reported per contract; payload evidence takes precedence. Independently nullable payloads do not erase Boolean evidence.",
+    "Names, Boolean counts and optional-field counts never establish a finding. A producer's literal writes establish either tag-specific payload presence or a pair of required Boolean fields with two or three distinct combinations, with both fields varying. Boolean members may use boolean, true | false or one unmerged nongeneric local alias of either. All four combinations, constant dimensions and optional/unknown dimensions are excluded. Expression-valued flags require the separate typed evidence described below. At most eight Boolean fields are compared. Only one relationship is reported per contract; existing literal/payload evidence takes precedence. Independently nullable payloads do not erase Boolean evidence.",
+    "With type services enabled, a synchronous nongeneric producer with exactly one own return, a final direct object return and a supported flat local contract also exposes strict equality predicates over the same earlier local const binding. Native types at both reads must be finite domains of at most sixteen string/number literals containing both distinct singleton comparison values. Literal constants and direct named-import/local enum members are supported; enum declarations and members are resolved by symbol identity and raw runtime literal values, including renamed imports and reexports. At most 128 candidate pairs per file are analyzed; exceeding the bound abstains from all typed findings in that file. No automatic fix is offered for these projections.",
+    "The const snapshot may be destructured or copied from another primitive binding, passed to callbacks, or read by closures without losing its value. Mutable bindings, parameters and module captures, property reads/getters, open/nullable/object/symbol domains, async producers, multiple own returns, generic/inherited/imported contracts and dynamic eval abstain. Nested callback returns do not belong to the producer. Enum namespace writes, aliases, escapes, computed accesses, calls and merged declarations in the analyzed file abstain. Cross-file enum declarations can supply type/constant identity; external mutation, dishonest declarations/assertions and runtime monkeypatching are not modeled. The analysis proves a relationship under those type and mutation assumptions, not domain intent or a whole-program ownership guarantee.",
     "Producer analysis requires a finite literal tag, every declared tag syntactically witnessed, exhaustive simple return paths without literal constant conditions, plain object returns, and consistent optional-field presence for each tag. It resolves only unmerged local aliases/interfaces without inheritance or generics, one local alias of a literal tag domain, and the built-in Promise around async returns. Callable or opaque own then properties abstain for async producers because Promise assimilation can replace the fulfilled value. Inherited then methods and external prototype mutation are not modeled. This is syntax-only evidence of field presence; explicit undefined, void and null payloads do not establish payload requirements, while expression value types are not inferred. Type-only assertion/satisfies/non-null wrappers, literal computed string keys and a sole-use const immediately before its return are recognized. Const alias chains, observation, mutation and dynamic eval abstain. Dynamic returns, spreads, dynamic computed keys, accessors, loops and try statements are deliberately skipped.",
     "A switch producer is supported only for a non-overloaded function declaration when its sole body statement switches on an unchanged direct string or number parameter, has unique same-kind literal labels and a default, and every nonempty case body is a sole object return or throw, optionally inside sole blocks. Empty labels may share the next terminating body; nested conditions, conditional returns, statement prefixes, breaks, other fallthrough, captured/closed inputs, dynamic eval and switches under preceding control flow abstain. Broad parameter domains establish input witnesses for each label and the default; this does not infer branch-specific runtime effects or expression value types. Path visits, depth and returned objects are bounded conservatively.",
     "These are refactoring advisories, not proven defects or proof that other writers cannot produce more states. Historical observations, partial results, unknown states and independently completing operations may need the broader contract. Review all readers and writers before migrating a shared contract; preserve every valid combination. A union of existing literal flag pairs is the smallest type-only replacement; a named disposition is a reviewed domain migration.",
@@ -5138,6 +5140,8 @@ var PREFER_DISCRIMINATED_UNION_DOCUMENTATION = {
     { id: "explicit-produced-variants", scenarioId: "produced-variants", title: "Give each produced variant its payload", outcome: "no-match", files: [{ path: "src/job.ts", source: 'function job(done: boolean): { phase: "queued"; ticket: string } | { phase: "complete" } { return done ? { phase: "complete" } : { phase: "queued", ticket: "t" }; }' }], focusPath: "src/job.ts", expectedCount: 0, public: true },
     { id: "flat-switch-producer", scenarioId: "switch-producer", title: "A complete dispatcher preserves each returned variant", outcome: "match", files: [{ path: "src/job.ts", source: 'function job(command: string): { phase: "queued" | "complete"; ticket?: string } { switch (command) { case "start": return { phase: "queued", ticket: "t" }; default: return { phase: "complete" }; } }' }], focusPath: "src/job.ts", expectedCount: 1, public: true },
     { id: "explicit-switch-variants", scenarioId: "switch-producer", title: "An explicit dispatcher result supports payload narrowing", outcome: "no-match", files: [{ path: "src/job.ts", source: 'function job(command: string): { phase: "queued"; ticket: string } | { phase: "complete" } { switch (command) { case "start": return { phase: "queued", ticket: "t" }; default: return { phase: "complete" }; } }' }], focusPath: "src/job.ts", expectedCount: 0, public: true },
+    { id: "immutable-state-projections", scenarioId: "state-projection", title: "Two predicates over one immutable phase cannot both be true", outcome: "match", files: [{ path: "src/projection.ts", source: 'type Phase = "ready" | "waiting" | "unknown"; declare function snapshot(): Phase; function state(): { ready: boolean; waiting: boolean } { const phase = snapshot(); return { ready: phase === "ready", waiting: phase === "waiting" }; }' }], focusPath: "src/projection.ts", expectedCount: 1, public: true },
+    { id: "authoritative-state", scenarioId: "state-projection", title: "Return the phase while preserving the independent timeout dimension", outcome: "no-match", files: [{ path: "src/projection.ts", source: 'type Phase = "ready" | "waiting" | "reconnecting" | "unknown"; declare function snapshot(): Phase; function state(timeout: boolean): { phase: Phase; timeout: boolean } { const phase = snapshot(); return { phase, timeout }; }' }], focusPath: "src/projection.ts", expectedCount: 0, public: true },
     {
       id: "safe-autofix",
       title: "Preserve an unused private producer's exact existing variants",

package/dist/{chunk-4USNCXB3.js → chunk-E2O4LN7G.js}

@@ -23411,6 +23411,94 @@ function literalTag(node) {
   return typeof node.value === "string" || typeof node.value === "number" || typeof node.value === "boolean" ? node.value : void 0;
 }
 
+// src/rules/_discriminated-union-projections.ts
+function projectedBooleanPairs(owner, returned2, source) {
+  if (owner.async || owner.generator || isPresent(owner.typeParameters) || owner.body?.type !== "BlockStatement" || parentOf(returned2) !== owner.body || owner.body.body.at(-1) !== returned2 || returned2.argument?.type !== "ObjectExpression") return [];
+  const contract = returnContract(owner, source);
+  const shape = contract === void 0 ? void 0 : objectContract(contract.members);
+  if (shape === void 0 || contract === void 0) return [];
+  const properties2 = returnedProperties([returned2.argument], shape)?.[0];
+  if (properties2 === void 0) return [];
+  const fields2 = [...shape.members].filter(([, member3]) => !member3.optional && booleanType(member3.typeAnnotation?.typeAnnotation, source));
+  if (fields2.length > 8) return [];
+  const comparisons = [];
+  for (const [field] of fields2) {
+    const value = properties2.get(field);
+    if (value?.type !== "BinaryExpression" || value.operator !== "===" || value.left.type !== "Identifier" || !constantSyntax(value.right, source)) continue;
+    const binding3 = localSnapshot(value.left, owner, source);
+    if (binding3 !== null) comparisons.push({ field, binding: binding3, left: value.left, right: value.right });
+  }
+  return comparisons.flatMap((left, index) => comparisons.slice(index + 1).filter((right) => right.binding === left.binding).map((right) => ({ reportNode: contract.reportNode, left, right })));
+}
+function localSnapshot(identifier, owner, source) {
+  const variable = findVariable(source.getScope(identifier), identifier.name);
+  const declaration = variable?.defs[0]?.node;
+  if (variable === null || variable.defs.length !== 1 || declaration?.type !== "VariableDeclarator" || !isConstDeclaration(parentOf(declaration)) || !isPresent(declaration.init) || enclosingFunction(declaration) !== owner || declaration.range[1] >= identifier.range[0] || !stableValueBinding(variable)) return null;
+  return variable;
+}
+function constantSyntax(node, source) {
+  if (node.type === "Literal") return typeof node.value === "string" || typeof node.value === "number" && Number.isFinite(node.value);
+  if (node.type !== "MemberExpression" || node.computed || node.optional || node.object.type !== "Identifier" || node.property.type !== "Identifier") return false;
+  const variable = findVariable(source.getScope(node.object), node.object.name);
+  const definition = variable?.defs[0]?.node;
+  if (variable === null || variable.defs.length !== 1 || definition?.type !== "TSEnumDeclaration" && definition?.type !== "ImportSpecifier" || !stableValueBinding(variable)) return false;
+  return variable.references.every((reference) => {
+    if (typeOnlyReference(reference)) return true;
+    const member3 = parentOf(reference.identifier);
+    if (member3?.type !== "MemberExpression" || member3.object !== reference.identifier || member3.computed || member3.optional || writtenMember(member3)) return false;
+    const use = parentOf(member3);
+    return !((use?.type === "CallExpression" || use?.type === "NewExpression") && use.callee === member3);
+  });
+}
+function enumConstant(node, native) {
+  if (node.type !== "MemberExpression") return false;
+  const root = native.node(node.object);
+  const member3 = native.node(node.property);
+  let symbol = root === void 0 ? void 0 : native.checker.getSymbolAtLocation(root);
+  if (symbol === void 0 || member3 === void 0) return false;
+  if ((symbol.flags & native.sync.SymbolFlags.Alias) !== 0) symbol = native.checker.getAliasedSymbol(symbol);
+  const declarations = symbol.declarations;
+  if (declarations.length !== 1 || declarations[0]?.kind !== native.ast.SyntaxKind.EnumDeclaration) return false;
+  const selected = native.checker.getSymbolAtLocation(member3)?.declarations;
+  return selected?.length === 1 && selected[0]?.kind === native.ast.SyntaxKind.EnumMember;
+}
+function projectedBooleanEvidence(file, candidates2) {
+  const nodes = candidates2.flatMap(({ left, right }) => [left.left, right.left, left.right, right.right]);
+  const types = file.typesOf(nodes);
+  const unions = types.flatMap((type) => type !== void 0 && type.isUnionType() ? [type] : []);
+  const lists = file.batch(unions.map((type) => type.getTypes.gen()));
+  let index = 0;
+  const domains = types.map((type) => type === void 0 ? void 0 : primitiveValues(type.isUnionType() ? lists[index++] ?? [] : [type], file));
+  const native = nativeTypes(file);
+  const constants = /* @__PURE__ */ new Map();
+  function constant(node, value) {
+    if (node.type === "Literal") return node.value === value;
+    let valid = constants.get(node);
+    if (valid === void 0) {
+      valid = enumConstant(node, native);
+      constants.set(node, valid);
+    }
+    return valid;
+  }
+  return candidates2.map(({ left, right }, ordinal) => {
+    const [a, b, x, y] = domains.slice(ordinal * 4, ordinal * 4 + 4);
+    const first = x?.[0];
+    const second = y?.[0];
+    return a !== void 0 && b !== void 0 && x?.length === 1 && y?.length === 1 && first !== void 0 && second !== void 0 && first !== second && constant(left.right, first) && constant(right.right, second) && a.includes(first) && a.includes(second) && b.includes(first) && b.includes(second);
+  });
+}
+function primitiveValues(types, file) {
+  if (types.length < 1 || types.length > 16) return void 0;
+  const values = [];
+  for (const type of types) {
+    if ((type.flags & (file.flags.StringLiteral | file.flags.NumberLiteral)) === 0) return void 0;
+    const value = type.value;
+    if (typeof value !== "string" && !(typeof value === "number" && Number.isFinite(value))) return void 0;
+    values.push(value);
+  }
+  return values;
+}
+
 // src/rules/prefer-discriminated-union.ts
 var NAME99 = "prefer-discriminated-union";
 var prefer_discriminated_union_default = defineRule({
@@ -23424,12 +23512,14 @@ var prefer_discriminated_union_default = defineRule({
     schema: [],
     messages: {
       preferProducedVariants: "This producer returns tag-specific payloads for `{{tag}}`, but its flat return contract makes them optional. If these variants define the domain, use a discriminated union with each variant's required payload, or give this producer a precise return type separate from the broader contract.",
-      preferProducedState: "This producer returns a restricted set of literal combinations for `{{fields}}`, while its Boolean fields permit all four. Review a union preserving every returned combination, or a typed disposition if these are domain phases. Other writers and readers of a shared contract require review."
+      preferProducedState: "This producer returns a restricted set of literal combinations for `{{fields}}`, while its Boolean fields permit all four. Review a union preserving every returned combination, or a typed disposition if these are domain phases. Other writers and readers of a shared contract require review.",
+      preferProjectedState: "This producer compares the same immutable primitive snapshot with distinct state values for `{{fields}}`, but its Boolean return contract also permits true/true. Review returning the authoritative state or preserving every produced combination in a union. Keep independent dimensions and unknown states; other writers and readers of a shared contract require review."
     }
   },
   createOnce(context) {
     const reportedContracts = /* @__PURE__ */ new Set();
     const producers = [];
+    const returns = /* @__PURE__ */ new Map();
     function rememberProducer(node) {
       producers.push(node);
     }
@@ -23449,6 +23539,7 @@ var prefer_discriminated_union_default = defineRule({
       before() {
         reportedContracts.clear();
         producers.length = 0;
+        returns.clear();
         const file = { filename: context.filename, cwd: context.cwd };
         if (isTestFile(file) || isGeneratedFile(file, context.sourceCode.text)) return false;
         return void 0;
@@ -23456,8 +23547,28 @@ var prefer_discriminated_union_default = defineRule({
       ArrowFunctionExpression: rememberProducer,
       FunctionDeclaration: rememberProducer,
       FunctionExpression: rememberProducer,
+      ReturnStatement(node) {
+        const owner = enclosingFunction(node);
+        if (owner !== null) returns.set(owner, returns.has(owner) ? null : node);
+      },
       "Program:exit"() {
         for (const producer of producers) checkProducer(producer);
+        if (hasIdentifierNamed(context.sourceCode, "eval")) return;
+        const candidates2 = [];
+        for (const producer of producers) {
+          const returned2 = returns.get(producer);
+          if (!isPresent(returned2)) continue;
+          candidates2.push(...projectedBooleanPairs(producer, returned2, context.sourceCode).filter(({ reportNode }) => !reportedContracts.has(reportNode)));
+          if (candidates2.length > 128) return;
+        }
+        if (candidates2.length === 0) return;
+        const evidence = tsrsServices(context)?.run((file) => projectedBooleanEvidence(file, candidates2));
+        if (!isPresent(evidence)) return;
+        candidates2.forEach(({ reportNode, left, right }, index) => {
+          if (evidence[index] !== true || reportedContracts.has(reportNode)) return;
+          reportedContracts.add(reportNode);
+          context.report({ node: reportNode, messageId: "preferProjectedState", data: { fields: [left.field, right.field].join("`, `") } });
+        });
       }
     };
   }

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   src_default
-} from "./chunk-4USNCXB3.js";
+} from "./chunk-E2O4LN7G.js";
 export {
   src_default as default
 };

package/package.json

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