Merge pull request #1 from nomasystems/release/0.9.0

Release 0.9.0

Author: angeltabar

.github/workflows/ci.yml

@@ -13,24 +13,35 @@ concurrency:
 
 jobs:
   analyze-and-test:
-    name: Analyze + test (Flutter ${{ matrix.flutter }})
-    # GitHub-hosted Ubuntu. Self-hosted runners are blocked for public repos
-    # by default at the org level (security: anyone can submit PRs).
-    # GitHub-hosted is free + unlimited for public OSS repos.
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
+    name: Analyze + test (Flutter ${{ matrix.flutter }} / ${{ matrix.os }})
+    # `ubuntu-latest` is the primary gate. `macos-latest` is added so we
+    # exercise the iOS / macOS pod / `image_picker` / `record` /
+    # `image_cropper` host-side codegen at least once per push — without
+    # this, breakage in those plugins only surfaces when a real iOS dev
+    # opens the example.
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
     strategy:
       fail-fast: false
       matrix:
-        # Pin to a stable channel; bump explicitly when the package's
-        # `environment.sdk` constraint is widened.
+        os: [ubuntu-latest, macos-latest]
         flutter: ["3.x"]
+        channel: [stable]
+        include:
+          # Informational job: track the next release channel so we get
+          # an early warning when the upcoming Flutter release breaks
+          # something. Failures here do not fail the workflow.
+          - os: ubuntu-latest
+            flutter: any
+            channel: beta
+            experimental: true
+    continue-on-error: ${{ matrix.experimental == true }}
     steps:
       - uses: actions/checkout@v5
 
       - uses: subosito/flutter-action@v2
         with:
-          channel: stable
+          channel: ${{ matrix.channel }}
           flutter-version: ${{ matrix.flutter }}
 
       - name: Flutter version
@@ -46,15 +57,81 @@ jobs:
         run: flutter analyze --fatal-infos --fatal-warnings
 
       - name: Tests + coverage
-        run: flutter test --coverage
+        # Golden baselines are generated on Linux (see regen-goldens.yml).
+        # macOS renders text/anti-aliasing differently, so the same PNGs
+        # never match there — exclude the golden tag on macOS only. Linux
+        # still runs (and gates) the full suite including goldens.
+        run: flutter test --coverage ${{ matrix.os == 'macos-latest' && '-x golden' || '' }}
 
       - name: Coverage gate (≥80%)
+        # Only the Linux/stable job gates coverage: it runs the full suite
+        # (goldens included) so its lcov is the complete picture. macOS
+        # excludes goldens, so its coverage is intentionally lower.
+        if: matrix.os == 'ubuntu-latest' && matrix.channel == 'stable'
         run: |
           awk 'BEGIN{lh=0; lf=0} /^LF:/{sub("LF:",""); lf+=$1} /^LH:/{sub("LH:",""); lh+=$1} END{ pct=(lh/lf)*100; printf "Coverage: %d/%d = %.2f%%\n", lh, lf, pct; if (pct < 80.0) { print "FAIL: coverage below 80% threshold"; exit 1 } }' coverage/lcov.info
 
+      # Upload coverage to Codecov on every successful run. The badge in
+      # README.md (https://codecov.io/gh/nomasystems/noma_chat_flutter)
+      # picks this up automatically. Requires the repo to be linked at
+      # codecov.io; public repos don't need a token. Only the ubuntu-latest
+      # / stable job uploads — running it from every matrix combo
+      # would create duplicate reports.
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix.os == 'ubuntu-latest' && matrix.channel == 'stable'
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+
       - name: Dartdoc dry-run
         run: dart doc --dry-run
 
+  example:
+    name: Example app compiles
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          flutter-version: "3.x"
+
+      - name: Pub get (package)
+        run: flutter pub get
+
+      - name: Pub get (example)
+        working-directory: example
+        run: flutter pub get
+
+      - name: Analyze example
+        working-directory: example
+        run: flutter analyze --fatal-infos --fatal-warnings
+
+      - name: Test example
+        working-directory: example
+        run: flutter test
+
+  performance:
+    name: Performance regression gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          flutter-version: "3.x"
+
+      - name: Install dependencies
+        run: flutter pub get
+
+      - name: Performance test (10k messages ≤ 8s)
+        run: flutter test test/cache/hive_chat_datasource_performance_test.dart --reporter=expanded
+
   pana:
     name: pub.dev score (pana)
     runs-on: ubuntu-latest

.github/workflows/regen-goldens.yml

@@ -0,0 +1,50 @@
+name: regen-goldens
+
+# Regenerates the golden baselines on Linux — the same OS that validates
+# them in `ci.yml` and `publish.yml` — and uploads them as an artifact so a
+# maintainer can download + commit the CI-matched PNGs. This solves the
+# local (macOS) vs CI (Linux) pixel-diff mismatch: goldens generated on a
+# developer's Mac never match the Linux runner's text rendering.
+#
+# Usage:
+#   1. Push the release branch (this runs automatically) or trigger manually.
+#   2. Download the `goldens` artifact from the run.
+#   3. Replace test/golden/goldens/ with its contents, commit, push.
+#
+# Uses `channel: stable` with no version pin to mirror `publish.yml` exactly,
+# so the regenerated baselines match the runner that gates publishing.
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - "release/**"
+
+jobs:
+  regen:
+    name: Regenerate golden baselines (Linux)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+
+      - name: Flutter version
+        run: flutter --version
+
+      - name: Install dependencies
+        run: flutter pub get
+
+      - name: Regenerate goldens
+        run: flutter test --update-goldens test/golden/
+
+      - name: Upload regenerated goldens
+        uses: actions/upload-artifact@v4
+        with:
+          name: goldens
+          path: test/golden/goldens/
+          if-no-files-found: error
+          retention-days: 3

.pubignore

@@ -1,7 +1,34 @@
 # Files / directories excluded from the tarball uploaded to pub.dev.
-# This is on top of pub's own default ignores (.git/, .dart_tool/, build/, …).
-# Anything excluded here is still kept in the GitHub repo; we only trim
-# what consumers don't need.
+#
+# IMPORTANT: when a .pubignore exists, pub uses it INSTEAD of .gitignore
+# (they are not merged). So every build/dev artefact that .gitignore keeps
+# out of the repo must ALSO be listed here, or it leaks into the published
+# tarball. Pub only hard-ignores .git/ and .dart_tool/ on its own — notably
+# NOT root build/, so the 70 MB test_cache .dill shipped until this list
+# grew. Anything excluded here is still kept in the GitHub repo; we only
+# trim what consumers don't need.
+
+# Build / cache artefacts (regenerated on demand; never useful to consumers).
+build/
+**/build/
+.dart_tool/
+**/.dart_tool/
+
+# Coverage reports and stray run logs.
+coverage/
+.coverage/
+*.log
+
+# IDE / editor / OS noise.
+.idea/
+.vscode/
+*.iml
+.DS_Store
+
+# Example platform host projects — pub.dev renders example/lib, consumers
+# never need the iOS/Android Runner scaffolding. Kept in the repo.
+example/ios/
+example/android/
 
 # Tests are useful in the repo but not for consumers; they would bloat the
 # tarball by megabytes and pub.dev does not render them anywhere.

ARCHITECTURE.md

@@ -168,7 +168,7 @@ Distinguishes real DMs from conceptual groups with 2 participants (e.g. a plan w
 - Optional `logger` in `ChatConfig`, propagated to `BearerAuthInterceptor` and the 4 main APIs (users, rooms, messages, contacts).
 - 11 `catch (_)` cache-best-effort sites replaced with `catch (e) { _logger?.call('warn', '...: $e'); }`.
 - `_openBoxSafe()` recovery logs + metrics `box_delete_failed` / `box_reopen_failed`.
-- Exported `MetricCallback`: `cache_hit`, `cache_miss`, `cache_eviction`, `cache_ttl_expired`.
+- `MetricCallback` (typedef `void Function(String metric, Map<String, dynamic> data)`) exported from `package:noma_chat/noma_chat_advanced.dart`. Events emitted today: `cache_hit`, `cache_miss`, `cache_stale_fallback`, `cache_eviction`, `cache_ttl_expired`, `box_corrupted`, `box_delete_failed`, `box_reopen_failed`, `schema_migration_wipe`.
 
 ## Backend integration