fix(ui, core): decreased cognitive complexity

.github/actions/pana/action.yml

@@ -47,7 +47,7 @@ runs:
       working-directory: ${{ inputs.working_directory }}
       shell: bash
       run: |
-        PANA=$(pana . --no-warning); PANA_SCORE=$(echo $PANA | sed -n "s/.*Points: \([0-9]*\)\/\([0-9]*\)./\1\/\2/p")
+        PANA=$(pana . --no-warning --project-root "${{ github.workspace }}"); PANA_SCORE=$(echo $PANA | sed -n "s/.*Points: \([0-9]*\)\/\([0-9]*\)./\1\/\2/p")
         echo "Score: $PANA_SCORE"
         IFS='/'; read -a SCORE_ARR <<< "$PANA_SCORE"; SCORE=SCORE_ARR[0];
         if (( $SCORE < ${{inputs.min_score}} )); then echo "The minimum score of ${{inputs.min_score}} was not met!"; exit 1; fi

.github/workflows/stream_flutter_workflow.yml

@@ -56,6 +56,12 @@ jobs:
     timeout-minutes: 15
     if: needs.gate.outputs.should_run == 'true'
     runs-on: ubuntu-latest
+    # Overrides the workflow-level block, so `contents: read` must be repeated.
+    # The complexity audit posts a sticky PR comment, which needs write access;
+    # without it the action still annotates but silently skips the comment.
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - name: "Git Checkout"
         uses: actions/checkout@v7
@@ -74,6 +80,29 @@ jobs:
         if: github.base_ref == 'master'
         run: |
           melos run lint:pub
+      # Gates cognitive complexity on declarations the PR actually touches.
+      #
+      # `targets` must be listed explicitly: the action defaults to `lib`, which
+      # does not exist at the root of this monorepo, so the default silently
+      # matches nothing and the gate passes unconditionally.
+      #
+      # PR-only, because `diff-base` needs a base ref. On push to master
+      # `github.base_ref` is empty, and an empty `diff-base` makes the action
+      # scan whole files rather than the diff — which would fail on the
+      # pre-existing hotspots this gate is not meant to block.
+      - name: "Cognitive Complexity"
+        if: github.event_name == 'pull_request'
+        uses: kevmoo/cognitive_complexity.dart@main
+        with:
+          targets: >-
+            packages/stream_chat/lib
+            packages/stream_chat_flutter/lib
+            packages/stream_chat_flutter_core/lib
+            packages/stream_chat_persistence/lib
+            packages/stream_chat_localizations/lib
+          diff-base: origin/${{ github.base_ref }}
+          fail-threshold: 15
+          fail-on-increase: true
 
   format:
     needs: gate

packages/stream_chat_flutter/lib/src/message_list_view/message_list_view_layout.dart

@@ -0,0 +1,114 @@
+import 'package:flutter/foundation.dart';
+
+/// The role a single item index plays in [MessageListLayout].
+enum MessageListItemSlot {
+  /// The widget at the list's leading edge.
+  ///
+  /// This is the footer for a reversed list and the header otherwise.
+  startEdge,
+
+  /// The pagination loading indicator nearest the list's leading edge.
+  bottomLoader,
+
+  /// A message from the loaded messages.
+  ///
+  /// Use [MessageListLayout.messageIndexAt] to resolve the message position.
+  message,
+
+  /// The pagination loading indicator nearest the list's trailing edge.
+  topLoader,
+
+  /// The widget at the list's trailing edge.
+  ///
+  /// This is the header for a reversed list and the footer otherwise.
+  endEdge,
+
+  /// The parent message of the thread being displayed, if any.
+  parentMessage,
+}
+
+/// The role a single separator index plays in [MessageListLayout].
+enum MessageListSeparatorSlot {
+  /// The gap adjoining [MessageListItemSlot.startEdge].
+  startEdgeGap,
+
+  /// The gap adjoining one of the pagination loading indicators.
+  loaderGap,
+
+  /// The separator between two adjacent messages.
+  betweenMessages,
+
+  /// The gap adjoining [MessageListItemSlot.endEdge].
+  endEdgeGap,
+
+  /// The separator introducing [MessageListItemSlot.parentMessage].
+  threadSeparator,
+}
+
+/// Maps the item and separator indices of the message list's scroll view onto
+/// the role each index plays.
+///
+/// The scroll view interleaves the loaded messages with five fixed slots — a
+/// header, a footer, a pagination loading indicator at either end and the
+/// thread's parent message. This type is the single place that knows how those
+/// slots are laid out, so index arithmetic is not repeated across the item,
+/// separator and item-key builders.
+@immutable
+final class MessageListLayout {
+  /// Creates a layout for a list holding [messageCount] messages.
+  const MessageListLayout({required this.messageCount});
+
+  /// The number of loaded messages in the list.
+  final int messageCount;
+
+  /// The number of fixed slots surrounding the messages: a header, a footer, a
+  /// pagination loading indicator at either end and the thread parent message.
+  static const fixedSlotCount = 5;
+
+  /// The item index of the first message, past the leading edge widget and the
+  /// pagination loading indicator that precede it.
+  static const firstMessageItemIndex = 2;
+
+  /// The total number of items in the scroll view.
+  int get itemCount => messageCount + fixedSlotCount;
+
+  /// The item index of the thread parent message, which occupies the final slot
+  /// and lives outside the loaded messages.
+  int get parentMessageIndex => itemCount - 1;
+
+  /// The role of the item at [index].
+  MessageListItemSlot itemSlotAt(int index) => switch (index) {
+    _ when index == itemCount - 1 => MessageListItemSlot.parentMessage,
+    _ when index == itemCount - 2 => MessageListItemSlot.endEdge,
+    _ when index == itemCount - 3 => MessageListItemSlot.topLoader,
+    1 => MessageListItemSlot.bottomLoader,
+    0 => MessageListItemSlot.startEdge,
+    _ => MessageListItemSlot.message,
+  };
+
+  /// The role of the separator at [index].
+  MessageListSeparatorSlot separatorSlotAt(int index) => switch (index) {
+    _ when index == itemCount - 2 => MessageListSeparatorSlot.threadSeparator,
+    _ when index == itemCount - 3 => MessageListSeparatorSlot.endEdgeGap,
+    0 => MessageListSeparatorSlot.startEdgeGap,
+    1 => MessageListSeparatorSlot.loaderGap,
+    _ when index == itemCount - 4 => MessageListSeparatorSlot.loaderGap,
+    _ => MessageListSeparatorSlot.betweenMessages,
+  };
+
+  /// The position in the loaded messages of the message shown at item [index].
+  ///
+  /// Only meaningful when [itemSlotAt] returns [MessageListItemSlot.message].
+  int messageIndexAt(int index) => index - firstMessageItemIndex;
+
+  /// The item index at which the message at [messageIndex] is shown.
+  ///
+  /// This is the inverse of [messageIndexAt].
+  int itemIndexOfMessage(int messageIndex) => messageIndex + firstMessageItemIndex;
+
+  @override
+  bool operator ==(Object other) => other is MessageListLayout && other.messageCount == messageCount;
+
+  @override
+  int get hashCode => messageCount.hashCode;
+}

packages/stream_chat_flutter/test/src/message_list_view/message_list_view_layout_test.dart

@@ -0,0 +1,205 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:stream_chat_flutter/src/message_list_view/message_list_view_layout.dart';
+
+// Reference implementations of the index arithmetic as it was written inline in
+// StreamMessageListView's item, separator and item-key builders. The layout
+// type must agree with these for every index, so the extraction cannot silently
+// change which widget lands in which slot.
+MessageListItemSlot referenceItemSlot(int index, int itemCount) {
+  if (index == itemCount - 1) return MessageListItemSlot.parentMessage;
+  if (index == itemCount - 2) return MessageListItemSlot.endEdge;
+  if (index == itemCount - 3) return MessageListItemSlot.topLoader;
+  if (index == 1) return MessageListItemSlot.bottomLoader;
+  if (index == 0) return MessageListItemSlot.startEdge;
+  return MessageListItemSlot.message;
+}
+
+MessageListSeparatorSlot referenceSeparatorSlot(int index, int itemCount) {
+  if (index == itemCount - 2) return MessageListSeparatorSlot.threadSeparator;
+  if (index == itemCount - 3) return MessageListSeparatorSlot.endEdgeGap;
+  if (index == 0) return MessageListSeparatorSlot.startEdgeGap;
+  if (index == 1 || index == itemCount - 4) return MessageListSeparatorSlot.loaderGap;
+  return MessageListSeparatorSlot.betweenMessages;
+}
+
+// Mirrors the original `itemKeyBuilder` closure.
+bool referenceHasMessageKey(int index, int itemCount, int messageCount) {
+  if (index < 2) return false;
+  if (index >= itemCount - 3) return false;
+  return index - 2 < messageCount;
+}
+
+void main() {
+  group('itemCount', () {
+    test('reserves five fixed slots around the messages', () {
+      expect(const MessageListLayout(messageCount: 0).itemCount, 5);
+      expect(const MessageListLayout(messageCount: 1).itemCount, 6);
+      expect(const MessageListLayout(messageCount: 10).itemCount, 15);
+    });
+  });
+
+  group('itemSlotAt', () {
+    test('lays out an empty list as fixed slots only', () {
+      const layout = MessageListLayout(messageCount: 0);
+
+      expect(
+        [for (var i = 0; i < layout.itemCount; i++) layout.itemSlotAt(i)],
+        [
+          MessageListItemSlot.startEdge,
+          MessageListItemSlot.bottomLoader,
+          MessageListItemSlot.topLoader,
+          MessageListItemSlot.endEdge,
+          MessageListItemSlot.parentMessage,
+        ],
+      );
+    });
+
+    test('places messages between the two pagination loaders', () {
+      const layout = MessageListLayout(messageCount: 3);
+
+      expect(
+        [for (var i = 0; i < layout.itemCount; i++) layout.itemSlotAt(i)],
+        [
+          MessageListItemSlot.startEdge,
+          MessageListItemSlot.bottomLoader,
+          MessageListItemSlot.message,
+          MessageListItemSlot.message,
+          MessageListItemSlot.message,
+          MessageListItemSlot.topLoader,
+          MessageListItemSlot.endEdge,
+          MessageListItemSlot.parentMessage,
+        ],
+      );
+    });
+
+    test('agrees with the original inline arithmetic for every index', () {
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        final layout = MessageListLayout(messageCount: messageCount);
+        for (var i = 0; i < layout.itemCount; i++) {
+          expect(
+            layout.itemSlotAt(i),
+            referenceItemSlot(i, layout.itemCount),
+            reason: 'item slot mismatch at index $i of $messageCount messages',
+          );
+        }
+      }
+    });
+
+    test('yields exactly messageCount message slots', () {
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        final layout = MessageListLayout(messageCount: messageCount);
+        final messageSlots = [
+          for (var i = 0; i < layout.itemCount; i++)
+            if (layout.itemSlotAt(i) == MessageListItemSlot.message) i,
+        ];
+
+        expect(messageSlots.length, messageCount);
+      }
+    });
+  });
+
+  group('separatorSlotAt', () {
+    test('agrees with the original inline arithmetic for every index', () {
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        final layout = MessageListLayout(messageCount: messageCount);
+        // A separated list builds itemCount - 1 separators.
+        for (var i = 0; i < layout.itemCount - 1; i++) {
+          expect(
+            layout.separatorSlotAt(i),
+            referenceSeparatorSlot(i, layout.itemCount),
+            reason: 'separator slot mismatch at index $i of $messageCount messages',
+          );
+        }
+      }
+    });
+
+    test('brackets the messages with loader gaps', () {
+      const layout = MessageListLayout(messageCount: 3);
+
+      expect(
+        [for (var i = 0; i < layout.itemCount - 1; i++) layout.separatorSlotAt(i)],
+        [
+          MessageListSeparatorSlot.startEdgeGap,
+          MessageListSeparatorSlot.loaderGap,
+          MessageListSeparatorSlot.betweenMessages,
+          MessageListSeparatorSlot.betweenMessages,
+          MessageListSeparatorSlot.loaderGap,
+          MessageListSeparatorSlot.endEdgeGap,
+          MessageListSeparatorSlot.threadSeparator,
+        ],
+      );
+    });
+  });
+
+  group('fixed slot indices', () {
+    test('parentMessageIndex is the final item and matches its slot', () {
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        final layout = MessageListLayout(messageCount: messageCount);
+
+        expect(layout.parentMessageIndex, layout.itemCount - 1);
+        expect(layout.itemSlotAt(layout.parentMessageIndex), MessageListItemSlot.parentMessage);
+      }
+    });
+
+    test('parentMessageIndex matches the original messages.length + 4 target', () {
+      // The old call site computed `messages.length + 2` and then added 2 again
+      // at the scroll site.
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        expect(MessageListLayout(messageCount: messageCount).parentMessageIndex, messageCount + 4);
+      }
+    });
+
+    test('firstMessageItemIndex is the first message slot', () {
+      const layout = MessageListLayout(messageCount: 3);
+
+      expect(MessageListLayout.firstMessageItemIndex, 2);
+      expect(layout.itemSlotAt(MessageListLayout.firstMessageItemIndex), MessageListItemSlot.message);
+      expect(layout.messageIndexAt(MessageListLayout.firstMessageItemIndex), 0);
+    });
+  });
+
+  group('message index mapping', () {
+    test('maps the first message slot to message 0', () {
+      const layout = MessageListLayout(messageCount: 5);
+
+      expect(layout.messageIndexAt(2), 0);
+      expect(layout.messageIndexAt(6), 4);
+    });
+
+    test('itemIndexOfMessage inverts messageIndexAt', () {
+      const layout = MessageListLayout(messageCount: 5);
+
+      for (var messageIndex = 0; messageIndex < 5; messageIndex++) {
+        final itemIndex = layout.itemIndexOfMessage(messageIndex);
+        expect(layout.messageIndexAt(itemIndex), messageIndex);
+        expect(layout.itemSlotAt(itemIndex), MessageListItemSlot.message);
+      }
+    });
+
+    test('message slots resolve to in-range message indices', () {
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        final layout = MessageListLayout(messageCount: messageCount);
+        for (var i = 0; i < layout.itemCount; i++) {
+          if (layout.itemSlotAt(i) != MessageListItemSlot.message) continue;
+
+          final messageIndex = layout.messageIndexAt(i);
+          expect(messageIndex, greaterThanOrEqualTo(0));
+          expect(messageIndex, lessThan(messageCount));
+        }
+      }
+    });
+
+    test('message slots match where the original built an item key', () {
+      for (var messageCount = 0; messageCount <= 20; messageCount++) {
+        final layout = MessageListLayout(messageCount: messageCount);
+        for (var i = 0; i < layout.itemCount; i++) {
+          expect(
+            layout.itemSlotAt(i) == MessageListItemSlot.message,
+            referenceHasMessageKey(i, layout.itemCount, messageCount),
+            reason: 'item key mismatch at index $i of $messageCount messages',
+          );
+        }
+      }
+    });
+  });
+}