@sarj/eslint-plugin 19.4.0 → 19.8.0

package/dist/catalog.js

@@ -2,7 +2,7 @@ import {
   publicDocumentation,
   ruleSpec,
   src_default
-} from "./chunk-6RX5RU75.js";
+} from "./chunk-G5BIV4A4.js";
 
 // src/docs/directive-disable-enable-pair.ts
 var DIRECTIVE_DISABLE_ENABLE_PAIR_DOCUMENTATION = {
@@ -4120,22 +4120,175 @@ var PREFER_AWAIT_IN_ASYNC_RETURN_DOCUMENTATION = {
 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.",
+  rationale: "A message-only or opaque 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. Reuse the native no-explicit-any rule, compiler narrowing and type-aware exhaustiveness checks.",
   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.",
+    "Accepting an inferred producer does not prove a finite inferred contract: object payloads or errAsync can widen a code to string. Annotate the existing Result/ResultAsync return when necessary. Native assignability, narrowing and exhaustive-handler checks remain authoritative.",
+    "Checks source-resolved local unions with required literal ok/success booleans, or status/state/kind/type/tag values ok/success versus err/error/failure/failed (case insensitive). Conflicting outcome tags abstain. A shared outcome tag does not also count as a domain error code. Named and namespace neverthrow Result/ResultAsync imports establish their generic error position.",
+    "Presence-selected unions require an error property on every failure branch and the same single required non-control value property on every success branch. Optional error/value fields, multiple value keys, loading states and error branches carrying the success value abstain. Required errorMessage and Error-suffixed failure channels are also reviewed; multiple custom channels abstain and a primary error payload retains precedence.",
+    "Broad string and unknown error channels, unshadowed native Error-family types and open string/unknown code fields receive review. Explicit Any stays with the existing no-explicit-any rule. Finite literal codes need no invented payload. Imported domain errors, validation-library errors, generic error parameters, ordinary formatters, legitimate absence and redacted failure states 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, 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."
+    "A directly returned failure object, neverthrow err/errAsync call or new Err with an interpolated template or proven string concatenation receives review. Without a code, the diagnostic asks for a domain contract; with a literal code, it asks for consumer formatting. Literal-only compositions, including earlier stable local constants, remain valid codes. Nested plain error objects, expression-bodied arrows and one direct await are supported. Import identity and value-space shadowing are checked; arbitrary aliases, 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: an infrastructure adapter may intentionally retain unknown/Error, and a final presentation boundary may accept every failure and render one message. Neither proves a recoverable domain rejection. 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: "presence-selected-message",
+      scenarioId: "presence-selected-result",
+      title: "An error-presence check still needs a useful error contract",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { value: T } | { error: string; field?: 'name' };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "presence-selected-domain-error",
+      scenarioId: "presence-selected-result",
+      title: "Retain the existing presence check with a finite error union",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "type SaveError = { code: 'duplicate'; name: string } | { code: 'denied' }; export type Outcome<T> = { value: T } | { error: SaveError };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "string-outcome-tag",
+      scenarioId: "string-outcome",
+      title: "An outcome tag distinguishes success from failure, not the failure's cause",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { kind: 'ok'; value: T } | { kind: 'error'; message: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "string-outcome-domain-code",
+      scenarioId: "string-outcome",
+      title: "Preserve the established string tag and add the actionable error",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { kind: 'ok'; value: T } | { kind: 'error'; error: { code: 'duplicate'; name: string } };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "opaque-error-channel",
+      scenarioId: "opaque-error",
+      title: "Unknown preserves the need to narrow but hides the domain's cases",
+      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, unknown>;"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "specific-error-channel",
+      scenarioId: "opaque-error",
+      title: "Expose the domain's rejection case without inventing context",
+      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, { code: 'unavailable' }>;"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "named-error-carrier",
+      scenarioId: "named-error-channel",
+      title: "A failure-only Error-suffixed field can still erase its cases",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { ok: true; value: T } | { ok: false; fallbackError: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "typed-named-error-carrier",
+      scenarioId: "named-error-channel",
+      title: "Preserve the existing field name with the required context",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { ok: true; value: T } | { ok: false; fallbackError: { code: 'unsupported'; requestedKind: string } };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "library-error-constructor",
+      scenarioId: "library-error-presentation",
+      title: "A proven Result constructor does not make formatted text actionable",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "import { err } from 'neverthrow'; export function reject(name: string) { return err(`Missing ${name}`); }"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "library-domain-constructor",
+      scenarioId: "library-error-presentation",
+      title: "Reuse the established Result library with a typed domain error",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "import { err, type Result } from 'neverthrow'; type Missing = { code: 'missing'; name: string }; export function reject(name: string): Result<never, Missing> { return err({ code: 'missing', name }); }"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
     {
       id: "message-only-result",
       title: "A failure erases identity into a message",
@@ -4194,6 +4347,66 @@ var PREFER_CODED_ERROR_RESULT_DOCUMENTATION = {
       expectedCount: 0,
       public: true
     },
+    {
+      id: "exclusive-message-outcome",
+      scenarioId: "partial-data",
+      title: "An exclusive failure still needs an actionable identity",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { ok: true; data: T } | { ok: false; error: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "independent-partial-outcomes",
+      scenarioId: "partial-data",
+      title: "Partial data and its independent error remain separate outcomes",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Partial<T> = { ok: true; data: T; error?: string } | { ok: false; data: T; error: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
+    {
+      id: "exclusive-error-state",
+      scenarioId: "absence-state",
+      title: "Conventional success and failure tags establish one Result",
+      outcome: "match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Outcome<T> = { status: 'success'; value: T } | { status: 'failure'; reason: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "legitimate-unconfigured-state",
+      scenarioId: "absence-state",
+      title: "A loading report can preserve an unconfigured absence state",
+      outcome: "no-match",
+      files: [
+        {
+          path: "app/result.ts",
+          source: "export type Source<T> = { status: 'loaded'; value: T } | { status: 'failed' | 'unconfigured'; reason: string };"
+        }
+      ],
+      focusPath: "app/result.ts",
+      expectedCount: 0,
+      public: true
+    },
     {
       id: "producer-renders-context",
       scenarioId: "consumer-formatting",
@@ -4227,6 +4440,54 @@ var PREFER_CODED_ERROR_RESULT_DOCUMENTATION = {
   ]
 };
 
+// src/docs/prefer-configured-cloud-scope.ts
+var PREFER_CONFIGURED_CLOUD_SCOPE_DOCUMENTATION = {
+  summary: "Prefer validated deployment configuration for account scope in outgoing cloud management requests.",
+  rationale: "A source-literal cloud account scope pins operational requests to one deployment even when the credential or environment changes.",
+  remediation: "Read the account ID from environment variables or injected configuration, validate it at startup, and pass the validated value to the request. Preserve independent security allowlists and fail closed when required configuration is missing.",
+  category: "correctness",
+  defaultLevel: "warning",
+  autofix: "none",
+  requiresTypeInformation: false,
+  limitations: [
+    "Initial coverage is canonical HTTPS Cloudflare v4 account-management URLs with a 32-character hexadecimal account segment sent to an unshadowed fetch, stable const alias, or fetch-default parameter. Other providers, SDKs, arbitrary endpoints, Worker names and resource IDs require separate evidence.",
+    "Follows bounded same-file const aliases, concatenations and template strings; an unknown account, mutable binding, function return, object property, fallback expression, URL/Request object or cross-file value is not inferred. Direct writes to the ambient fetch or its global receivers veto findings; indirect runtime monkeypatches are not modeled.",
+    "Analysis stops at 16 nested expressions or fetch aliases, 256 URL-expression visits per request, 128 string fragments or 8,192 UTF-16 code units of assembled URL text. These limits deliberately leave more complex expressions unreported.",
+    "Scripts remain covered. Test/fixture and generated files are excluded. Comparisons, schemas, allowlists and unused URL strings do not produce findings. Each originating account literal is reported at most once per file.",
+    "This is a warning without an automatic fix: the deployment configuration boundary and independent authorization policy require review. Application code should import validated configuration as required by no-raw-env; browser-exposed variables must never contain secrets."
+  ],
+  references: [
+    "https://developers.cloudflare.com/workers/wrangler/system-environment-variables/",
+    "https://eslint.org/docs/latest/rules/no-restricted-syntax"
+  ],
+  examples: [
+    {
+      id: "literal-account-scope",
+      title: "Move outgoing account scope into deployment configuration",
+      outcome: "match",
+      files: [{
+        path: ".github/scripts/publish.mjs",
+        source: "const accountId = '0123456789abcdef0123456789abcdef';\nconst base = `https://api.cloudflare.com/client/v4/accounts/${accountId}`;\nexport async function publish(path, request = fetch) { return request(`${base}/${path}`); }"
+      }],
+      focusPath: ".github/scripts/publish.mjs",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "validated-account-scope",
+      title: "Pass validated deployment configuration to the request",
+      outcome: "no-match",
+      files: [{
+        path: ".github/scripts/publish.mjs",
+        source: "import { env } from './env.mjs';\nconst base = `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}`;\nexport async function publish(path, request = fetch) { return request(`${base}/${path}`); }"
+      }],
+      focusPath: ".github/scripts/publish.mjs",
+      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.",
@@ -6629,6 +6890,7 @@ var RULE_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-configured-cloud-scope": PREFER_CONFIGURED_CLOUD_SCOPE_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,