v3: breaking/behavioral changes to enable the remaining DCM lint rules

[spydon]

Context

We've been ratcheting on the shared DCM config in supabase_lints, enabling rules one at a time as their violations are fixed (started in #1414, followed by a stack of PRs). Most rules are now enabled. A handful of still-ignored rules can only be satisfied with breaking or behavioral changes, so they're deferred to v3. This issue tracks those.

Breaking / behavioral changes to make

1. RealtimeClient.push should return void — rule function-always-returns-null

RealtimeClient.push(Message) is declared to return String? but always returns null; the return type is vestigial.

• Change the signature to void push(Message message).
• Breaking: public API signature change.
• File: packages/realtime_client/lib/src/realtime_client.dart
• Currently suppressed with an inline // ignore: function-always-returns-null.

2. Override == / hashCode on exception & response subclasses — rule prefer-overriding-parent-equality

These public subclasses add fields but inherit ==/hashCode from their parent, so two instances that differ only by the subclass field currently compare equal. Implement ==/hashCode that include the new fields:

• AuthUnknownException (adds originalError) — packages/gotrue/lib/src/types/auth_exception.dart
• AuthWeakPasswordException (adds reasons) — same file
• SignedUploadURLResponse (adds token) — packages/storage_client/lib/src/types.dart
• Behavioral: changes equality semantics for these public types (consumers that rely on the current parent-based equality would see different results).

Rules with only a partial public-API (breaking) subset — assess when picked up

These are mostly internal/private (and can be fixed non-breaking at any time), but each has a small public-API subset that would be breaking and should be triaged during v3:

• prefer-prefixed-global-constants — e.g. the exported version constants in functions_client/gotrue/etc.
• avoid-never-passed-parameters — never-passed parameters that sit on public constructors.
• prefer-correct-callback-field-name — public callback field names.

Explicitly NOT breaking (handled outside v3)

For the record, these looked like they might need breaking changes but don't:

• avoid-unnecessary-nullable-return-type / avoid-unnecessary-nullable-parameters: the lib sites are either private (_copyWithType, _initSupabaseAuthClient, _parseMediaType) and fixable non-breaking, or conditional-import requirements where the nullable type is correct (condPlatform* returns null in platform_stub.dart and is exposed as Constants.platform -> String?; local_storage_stub.accessToken). These will be handled with in-place fixes or inline ignores, not in v3.

---

Update — further investigation of three more rules

prefer-correct-callback-field-name — mostly breaking

Of its 19 lib violations, ~7 are private fields (_onAuthStateChangeController, _converter, _retryDelay, _getAccessToken, _queryBuilder) which are non-breaking to rename, but the rest are public fields whose rename to the on*/*Builder convention would be breaking and is also semantically questionable (they aren't event callbacks):

• RealtimeClient.transport, RealtimeClient.encode, RealtimeClient.decode, RealtimeClient.reconnectAfterMs, RealtimeClient.logger, RealtimeClient.customAccessToken
• RealtimeClientOptions.transport
• SupabaseClient.accessToken
• RetryTimer.callback, RetryTimer.timerCalc
• Binding.callback (types.dart), Push.callback

Decision needed in v3: rename these public fields (breaking) or leave the rule disabled.

prefer-explicit-function-type — mostly NOT fixable (not breaking)

The bare Function types are largely mandated by the Future interface overrides (PostgrestBuilder.catchError(Function onError, ...), then({Function? onError})) and cannot be given an explicit type without diverging from the override signature. One public field (RealtimeClient.stateChangeCallbacks, Map<String, List<Function>>) would be breaking to retype. Not a v3 candidate; likely stays disabled or gets inline ignores.

prefer-correct-json-casts — NOT breaking (worth fixing outside v3)

Its 5 sites are internal fromJson casts that DCM warns will throw at runtime (e.g. json['newPresences'] as List<Presence>, body as Map<String, String>?). These are non-breaking correctness fixes and should be handled in a normal PR, not v3.