@sarj/eslint-plugin 19.0.2 → 19.4.0

package/dist/catalog.js

@@ -2,7 +2,7 @@ import {
   publicDocumentation,
   ruleSpec,
   src_default
-} from "./chunk-KBGBBVAC.js";
+} from "./chunk-6RX5RU75.js";
 
 // src/docs/directive-disable-enable-pair.ts
 var DIRECTIVE_DISABLE_ENABLE_PAIR_DOCUMENTATION = {
@@ -4116,6 +4116,117 @@ var PREFER_AWAIT_IN_ASYNC_RETURN_DOCUMENTATION = {
   ]
 };
 
+// src/docs/prefer-coded-error-result.ts
+var PREFER_CODED_ERROR_RESULT_DOCUMENTATION = {
+  summary: "Return a stable error code and typed context instead of only a rendered failure message.",
+  defaultLevel: "warning",
+  rationale: "A message-only failure hides the identity needed for repair, conflict handling, localization and exhaustive dispatch. Preserve a finite error code and the minimum handling context; let the consumer format its message.",
+  remediation: "Use the existing Result or outcome union with a finite error code and variant-specific context. Preserve public behavior through a presentation adapter, and handle or propagate each relevant variant without parsing message text.",
+  category: "correctness",
+  autofix: "none",
+  limitations: [
+    "Checks source-resolved local unions with required literal ok/success true and false branches, and named neverthrow Result/ResultAsync imports. Broad string error/message/reason payloads and open string code fields are review candidates. String literal error-code unions remain valid.",
+    "Local aliases, unmerged interfaces without inheritance and generic substitutions are bounded to 16 resolution levels, 64 union members and 256 traversal steps. Imported local declarations, namespace imports, conditional/intersection/mapped types and unresolved contracts abstain. Optional discriminants, independent success/error payloads and partial-data failures are excluded.",
+    "Required code/kind/type/tag fields of unresolved or imported type defer to the type checker; a finite code does not prove that its cases or payloads are useful. Generic error parameters are retained rather than guessed. Ordinary string formatters, absence, validation-library errors and redacted failure states without a string payload are not flagged.",
+    "A directly returned plain object with literal ok/success false and a literal string code/kind/type/tag also receives review when its message/reason is an interpolated template or proven string concatenation. Nested plain error objects and expression-bodied arrows are supported. Spreads, accessors, computed keys, helper formatting calls and nonliteral codes abstain. This proves formatting ownership, not which context the domain must expose; presentation adapters remain a reviewed exception.",
+    "This warning requests domain review: a final presentation boundary may intentionally accept every failure and render one message. No fix invents error codes, fields, handlers or changes serialization, exception unwinding, transactions, retries or logging."
+  ],
+  references: [
+    "https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions",
+    "https://github.com/supermacro/neverthrow"
+  ],
+  examples: [
+    {
+      id: "message-only-result",
+      title: "A failure erases identity into a message",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Result<T> = { ok: true; data: T } | { ok: false; message: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "code-and-context",
+      title: "The consumer can choose behavior and format context",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "type Error = { code: 'duplicate'; name: string } | { code: 'invalid_transition' }; export type Result<T> = { ok: true; data: T } | { ok: false; error: Error };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "generic-error-instantiation",
+      scenarioId: "generic-error",
+      title: "A concrete generic error channel erases its identity",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }; export type Saved = Result<number, string>;"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "finite-error-codes",
+      scenarioId: "generic-error",
+      title: "An error code needs no invented payload",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }; export type Saved = Result<number, 'duplicate' | 'invalid_transition'>;"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "producer-renders-context",
+      scenarioId: "consumer-formatting",
+      title: "A code alone does not move message formatting to the consumer",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export function reject(name: string) { return { ok: false, code: 'duplicate', message: `Duplicate ${name}` }; }"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "consumer-renders-context",
+      scenarioId: "consumer-formatting",
+      title: "Retain the typed context and format after handling the code",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "type Duplicate = { code: 'duplicate'; name: string }; export function reject(name: string): { ok: false; error: Duplicate } { return { ok: false, error: { code: 'duplicate', name } }; } export function format(error: Duplicate): string { return `Duplicate ${error.name}`; }"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    }
+  ]
+};
+
 // src/docs/prefer-constant-time-secret-compare.ts
 var PREFER_CONSTANT_TIME_SECRET_COMPARE_DOCUMENTATION = {
   summary: "Prefer a supported constant-time comparison primitive for secret-like values.",
@@ -4148,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 },
@@ -6514,6 +6628,7 @@ var RULE_DOCUMENTATION = {
   "no-zod-native-enum": NO_ZOD_NATIVE_ENUM_DOCUMENTATION,
   "no-zod-parse-typed-object": NO_ZOD_PARSE_TYPED_OBJECT_DOCUMENTATION,
   "prefer-await-in-async-return": PREFER_AWAIT_IN_ASYNC_RETURN_DOCUMENTATION,
+  "prefer-coded-error-result": PREFER_CODED_ERROR_RESULT_DOCUMENTATION,
   "prefer-constant-time-secret-compare": PREFER_CONSTANT_TIME_SECRET_COMPARE_DOCUMENTATION,
   "prefer-dependency-interface": PREFER_DEPENDENCY_INTERFACE_DOCUMENTATION,
   "prefer-discriminated-union": PREFER_DISCRIMINATED_UNION_DOCUMENTATION,