@sarj/eslint-plugin 19.2.0 → 19.4.0

package/dist/catalog.js

@@ -2,7 +2,7 @@ import {
   publicDocumentation,
   ruleSpec,
   src_default
-} from "./chunk-JBAPB4JX.js";
+} from "./chunk-6RX5RU75.js";
 
 // src/docs/directive-disable-enable-pair.ts
 var DIRECTIVE_DISABLE_ENABLE_PAIR_DOCUMENTATION = {
@@ -4259,22 +4259,25 @@ var PREFER_DEPENDENCY_INTERFACE_DOCUMENTATION = {
 
 // src/docs/prefer-discriminated-union.ts
 var PREFER_DISCRIMINATED_UNION_DOCUMENTATION = {
-  summary: "Prefer discriminated unions for result contracts and locally proven tag-specific return payloads.",
+  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.",
   category: "correctness",
   autofix: "safe",
   limitations: [
-    "The legacy boolean-result advisory recognizes local status and payload names; those names do not prove that partial-success outcomes are forbidden. Review the domain before changing its representation.",
+    "Names, Boolean counts and optional-field counts never establish a finding. A producer's direct 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. All four combinations, constant 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.",
     "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, and the built-in Promise around async returns. This is syntax-only evidence of field presence; explicit undefined, void and null payloads are skipped, while expression value types are not inferred. Dynamic returns, spreads, 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 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.",
-    "Returned variants prove this producer's key relationships, not all legal consumers of a shared type. Automatic fixes are limited to an unused private nongeneric synchronous function with a direct inline contract and one literal-object conditional return; they preserve original member types and all runtime code. Shared/observed contracts and generated/declaration/test files remain excluded."
+    "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.",
+    "Automatic fixes are limited to an unused private nongeneric synchronous function with a direct inline contract and one conditional return containing at most four literal objects. They narrow only the existing discriminator or implicated Boolean pair and preserve other member types and all runtime code, including condition evaluation, object creation, identity and exceptions. Nested conditionals are supported. Shared/observed contracts, aliases, exports, async functions, comments, expression payloads and generated/declaration/test files remain excluded. Public interfaces, serialization and cancellation are never rewritten."
   ],
   references: ["https://functional-architecture.org/make_illegal_states_unrepresentable/", "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"],
   examples: [
     { id: "explicit-result-branches", title: "Use explicit result branches", outcome: "no-match", files: [{ path: "src/result.ts", source: "type Result = { ok: true; data: string } | { ok: false; error: string };" }], focusPath: "src/result.ts", expectedCount: 0, public: true },
-    { id: "optional-result-payloads", title: "Review optional result payloads", outcome: "match", files: [{ path: "src/result.ts", source: "type Result = { ok: boolean; data?: string; error?: string };" }], focusPath: "src/result.ts", expectedCount: 1, public: true },
+    { id: "optional-result-payloads", title: "A producer establishes the status-to-payload relationship", outcome: "match", files: [{ path: "src/result.ts", source: 'function result(ok: boolean): { ok: boolean; data?: string; error?: string } { return ok ? { ok: true, data: "value" } : { ok: false, error: "failed" }; }' }], focusPath: "src/result.ts", expectedCount: 1, public: true },
+    { id: "failure-dispositions", scenarioId: "boolean-state", title: "A producer returns retry, terminal and saved-partial combinations", outcome: "match", files: [{ path: "src/failure.ts", source: "function failure(retry: boolean, saved: boolean): { retriable: boolean; persisted: boolean } { return saved ? { retriable: false, persisted: true } : retry ? { retriable: true, persisted: false } : { retriable: false, persisted: false }; }" }], focusPath: "src/failure.ts", expectedCount: 1, public: true },
+    { id: "independent-observations", scenarioId: "boolean-state", title: "Independent observations retain all four combinations", outcome: "no-match", files: [{ path: "src/observations.ts", source: "function observations(a: boolean, b: boolean): { started: boolean; reported: boolean } { return a ? b ? { started: true, reported: true } : { started: true, reported: false } : b ? { started: false, reported: true } : { started: false, reported: false }; }" }], focusPath: "src/observations.ts", expectedCount: 0, public: true },
     { id: "flat-produced-variants", scenarioId: "produced-variants", title: "Preserve producer variant relationships", outcome: "match", files: [{ path: "src/job.ts", source: 'function job(done: boolean): { phase: "queued" | "complete"; ticket?: string } { return done ? { phase: "complete" } : { phase: "queued", ticket: "t" }; }' }], focusPath: "src/job.ts", expectedCount: 1, public: true },
     { 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 },

package/dist/{chunk-JBAPB4JX.js → chunk-6RX5RU75.js}

@@ -22099,11 +22099,43 @@ function discriminatedUnionReturns(node, sourceCode2) {
     if (member3.optional) continue;
     const domain = tagDomain(member3.typeAnnotation?.typeAnnotation);
     if (domain !== void 0 && hasTagSpecificPayload(name, domain, shape.optional, returned2)) {
-      return { reportNode: contract.reportNode, tag: name, members: shape.members, returned: returned2 };
+      return { reportNode: contract.reportNode, relationship: { kind: "presence", tag: name }, members: shape.members, returned: returned2 };
+    }
+  }
+  const fields2 = correlatedBooleanFields(shape, returned2);
+  return fields2 === void 0 ? void 0 : {
+    reportNode: contract.reportNode,
+    relationship: { kind: "boolean-pair", fields: fields2 },
+    members: shape.members,
+    returned: returned2
+  };
+}
+function correlatedBooleanFields(shape, returned2) {
+  const fields2 = [...shape.members].filter(([, member3]) => !member3.optional && member3.typeAnnotation?.typeAnnotation.type === "TSBooleanKeyword").map(([name]) => name);
+  if (fields2.length > 8) return void 0;
+  for (const [index, left] of fields2.entries()) {
+    for (const right of fields2.slice(index + 1)) {
+      const combinations = booleanCombinations(left, right, returned2);
+      if (combinations !== void 0 && restrictedVaryingPair(combinations)) return { left, right };
     }
   }
   return void 0;
 }
+function booleanCombinations(left, right, returned2) {
+  const combinations = /* @__PURE__ */ new Set();
+  for (const properties2 of returned2) {
+    const a = properties2.get(left);
+    const b = properties2.get(right);
+    if (a?.type !== "Literal" || typeof a.value !== "boolean" || b?.type !== "Literal" || typeof b.value !== "boolean") return void 0;
+    combinations.add(`${Number(a.value)}${Number(b.value)}`);
+  }
+  return combinations;
+}
+function restrictedVaryingPair(combinations) {
+  if (combinations.size < 2 || combinations.size === 4) return false;
+  const values = [...combinations];
+  return [0, 1].every((index) => values.some((value) => value[index] === "0") && values.some((value) => value[index] === "1"));
+}
 function returnContract(node, sourceCode2) {
   const annotation = node.returnType;
   if (!isPresent(annotation)) return void 0;
@@ -22148,7 +22180,7 @@ function objectContract(elements) {
     members2.set(name, member3);
     if (member3.optional) optional.add(name);
   }
-  return optional.size === 0 ? void 0 : { members: members2, optional };
+  return { members: members2, optional };
 }
 function returnedProperties(objects, contract) {
   const returned2 = [];
@@ -22334,102 +22366,18 @@ function literalTag(node) {
 
 // src/rules/prefer-discriminated-union.ts
 var NAME94 = "prefer-discriminated-union";
-var STATUS_MEMBER_NAMES = /* @__PURE__ */ new Set([
-  "success",
-  "ok"
-]);
-var FAILURE_MEMBER_NAMES = /* @__PURE__ */ new Set([
-  "error",
-  "errors",
-  "reason",
-  "cause"
-]);
-var SUCCESS_PAYLOAD_MEMBER_NAMES = /* @__PURE__ */ new Set([
-  "data",
-  "events",
-  "payload",
-  "response",
-  "result",
-  "value"
-]);
-var REQUIRED_STATUS_MEMBER_COUNT = 1;
-var FUNCTION_RETURN_OWNER_TYPES = /* @__PURE__ */ new Set([
-  "ArrowFunctionExpression",
-  "FunctionDeclaration",
-  "FunctionExpression",
-  "TSDeclareFunction",
-  "TSEmptyBodyFunctionExpression",
-  "TSFunctionType",
-  "TSMethodSignature"
-]);
-function looksLikeMutuallyExclusiveState(typeLiteral) {
-  let statusMemberCount = 0;
-  let hasFailurePayload = false;
-  let hasSuccessPayload = false;
-  let hasUnrecognizedMember = false;
-  for (const member3 of typeLiteral.members) {
-    if (member3.type !== "TSPropertySignature") {
-      hasUnrecognizedMember = true;
-      continue;
-    }
-    const name = getMemberName(member3);
-    if (name !== null && STATUS_MEMBER_NAMES.has(name) && isBooleanTyped(member3) && !member3.optional) {
-      statusMemberCount += 1;
-      continue;
-    }
-    if (!member3.optional || isBooleanTyped(member3) || name === null) {
-      hasUnrecognizedMember = true;
-      continue;
-    }
-    if (FAILURE_MEMBER_NAMES.has(name)) {
-      hasFailurePayload = true;
-    } else if (SUCCESS_PAYLOAD_MEMBER_NAMES.has(name)) {
-      hasSuccessPayload = true;
-    } else {
-      hasUnrecognizedMember = true;
-    }
-  }
-  return statusMemberCount === REQUIRED_STATUS_MEMBER_COUNT && hasFailurePayload && (hasSuccessPayload || !hasUnrecognizedMember);
-}
-function getMemberName(member3) {
-  if (member3.type !== "TSPropertySignature" || member3.computed) {
-    return null;
-  }
-  const { key } = member3;
-  if (key.type === "Identifier") {
-    return key.name;
-  }
-  if (key.type === "Literal" && typeof key.value === "string") {
-    return key.value;
-  }
-  return null;
-}
-function isBooleanTyped(member3) {
-  return member3.typeAnnotation?.typeAnnotation.type === "TSBooleanKeyword";
-}
-function inlineReturnTypeLiteral(node) {
-  let annotation = null;
-  if (node.parent.type === "TSTypeAnnotation") {
-    annotation = node.parent;
-  } else if (node.parent.type === "TSTypeParameterInstantiation" && node.parent.params.length === 1 && node.parent.params[0] === node && node.parent.parent.type === "TSTypeReference" && node.parent.parent.typeName.type === "Identifier" && node.parent.parent.typeName.name === "Promise" && node.parent.parent.parent.type === "TSTypeAnnotation") {
-    annotation = node.parent.parent.parent;
-  }
-  if (annotation === null) return null;
-  const owner = annotation.parent;
-  return FUNCTION_RETURN_OWNER_TYPES.has(owner.type) && "returnType" in owner && owner.returnType === annotation ? annotation : null;
-}
 var prefer_discriminated_union_default = defineRule({
   meta: {
     type: "suggestion",
     fixable: "code",
     docs: {
-      description: "Prefer discriminated unions for result contracts and locally proven tag-specific return payloads.",
+      description: "Preserve producer-proven tag/payload and Boolean state relationships in return types.",
       url: docsUrl(NAME94)
     },
     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.",
-      preferDiscriminatedUnion: "This object type combines a boolean status with optional payloads. If success and failure are mutually exclusive, consider a discriminated union such as `{ ok: true; data: T } | { ok: false; error: E }`."
+      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."
     }
   },
   createOnce(context) {
@@ -22443,30 +22391,13 @@ var prefer_discriminated_union_default = defineRule({
       if (result === void 0 || reportedContracts.has(result.reportNode)) return;
       reportedContracts.add(result.reportNode);
       const fix = privateVariantReturn(context.sourceCode, context.filename, node, result);
+      const relationship = result.relationship;
       context.report({
         node: result.reportNode,
-        messageId: "preferProducedVariants",
         ...fix !== null && { fix },
-        data: { tag: result.tag }
+        ...relationship.kind === "presence" ? { messageId: "preferProducedVariants", data: { tag: relationship.tag } } : { messageId: "preferProducedState", data: { fields: [relationship.fields.left, relationship.fields.right].join("`, `") } }
       });
     }
-    function checkTypeLiteral(typeLiteral, reportNode) {
-      if (looksLikeMutuallyExclusiveState(typeLiteral) && !reportedContracts.has(reportNode)) {
-        reportedContracts.add(reportNode);
-        const fix = inlineProducerFix(reportNode);
-        context.report({
-          node: reportNode,
-          messageId: "preferDiscriminatedUnion",
-          ...fix !== null && { fix }
-        });
-      }
-    }
-    function inlineProducerFix(reportNode) {
-      if (reportNode.type !== "TSTypeAnnotation" || reportNode.parent.type !== "FunctionDeclaration") return null;
-      const owner = reportNode.parent;
-      const result = discriminatedUnionReturns(owner, context.sourceCode);
-      return result === void 0 ? null : privateVariantReturn(context.sourceCode, context.filename, owner, result);
-    }
     return {
       before() {
         reportedContracts.clear();
@@ -22480,34 +22411,23 @@ var prefer_discriminated_union_default = defineRule({
       FunctionExpression: rememberProducer,
       "Program:exit"() {
         for (const producer of producers) checkProducer(producer);
-      },
-      TSInterfaceDeclaration(node) {
-        if (node.extends.length > 0) {
-          return;
-        }
-        checkTypeLiteral({ members: node.body.body }, node);
-      },
-      TSTypeLiteral(node) {
-        if (node.parent.type === "TSTypeAliasDeclaration") checkTypeLiteral(node, node.parent);
-        const annotation = inlineReturnTypeLiteral(node);
-        if (annotation !== null) checkTypeLiteral(node, annotation);
       }
     };
   }
 });
 function privateVariantReturn(sourceCode2, filename, owner, result) {
   const annotation = owner.returnType?.typeAnnotation;
-  if (owner.type !== "FunctionDeclaration" || owner.id === null || !returnsOnlyConditionalObject(owner) || annotation?.type !== "TSTypeLiteral" || result.reportNode !== owner.returnType || result.returned.length !== 2 || sourceCode2.getCommentsInside(owner).length > 0 || !isUnusedPrivateBinding(sourceCode2, owner, owner.id, filename) || !retainsNamedTypeUses(sourceCode2, annotation)) return null;
+  if (owner.type !== "FunctionDeclaration" || owner.id === null || !returnsOnlyConditionalObject(owner) || annotation?.type !== "TSTypeLiteral" || result.reportNode !== owner.returnType || result.returned.length > 4 || sourceCode2.getCommentsInside(owner).length > 0 || !isUnusedPrivateBinding(sourceCode2, owner, owner.id, filename) || !retainsNamedTypeUses(sourceCode2, annotation)) return null;
   const variants2 = result.returned.map((properties2) => privateVariantType(properties2, result, sourceCode2));
   if (variants2.some((variant) => variant === null)) return null;
-  const text = `${variants2.join(" | ")}${sourceCode2.getText(annotation).replace(/[^\r\n]/gu, "")}`;
+  const text = `${variants2.join(" | ")}${sourceCode2.getText(annotation).replace(/[^\r\n\u2028\u2029]/gu, "")}`;
   return (fixer) => fixer.replaceText(annotation, text);
 }
 function returnsOnlyConditionalObject(fn) {
   if (fn.async || fn.generator || isPresent(fn.typeParameters)) return false;
   const statements = fn.body?.body ?? [];
   const [returned2] = statements;
-  return statements.length === 1 && returned2?.type === "ReturnStatement" && returned2.argument?.type === "ConditionalExpression" && returned2.argument.consequent.type === "ObjectExpression" && returned2.argument.alternate.type === "ObjectExpression";
+  return statements.length === 1 && returned2?.type === "ReturnStatement" && returned2.argument?.type === "ConditionalExpression";
 }
 function privateVariantType(properties2, result, sourceCode2) {
   if ([...properties2.values()].some((value) => value.type !== "Literal" || typeof value.value === "object" && value.value !== null || typeof value.value === "number" && !Number.isFinite(value.value))) return null;
@@ -22517,7 +22437,8 @@ function privateVariantType(properties2, result, sourceCode2) {
     if (value === void 0) continue;
     const annotation = member3.typeAnnotation?.typeAnnotation;
     if (annotation === void 0) return null;
-    const type = name === result.tag ? sourceCode2.getText(value) : sourceCode2.getText(annotation);
+    const narrow = result.relationship.kind === "presence" ? name === result.relationship.tag : name === result.relationship.fields.left || name === result.relationship.fields.right;
+    const type = narrow ? sourceCode2.getText(value) : sourceCode2.getText(annotation);
     fields2.push(`${member3.readonly ? "readonly " : ""}${sourceCode2.getText(member3.key)}: ${type}`);
   }
   return `{ ${fields2.join("; ")} }`;

package/dist/index.js

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

package/package.json

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