docs(repo): add STYLE_GUIDE.md and TESTING.md adapted from Flutter's guides

[xsahil03x]

Summary

• Adds STYLE_GUIDE.md at the repo root — a canonical style guide adapted from Flutter's repo style guide, reshaped for the design-system + LLC-transport structure of this repo.
• Adds TESTING.md at the repo root — a companion doc on how to write good tests adapted from Flutter's Writing-Effective-Tests.
• Wires CLAUDE.md to open with a pointer directing AI agents to read STYLE_GUIDE.md before writing or reviewing code, plus a TESTING.md link for test-writing tasks.

Mirrors the equivalent PR in stream-chat-flutter #2793, tuned for this repo's actual conventions.

What's in STYLE_GUIDE

• Quick rules — a scannable checklist near the top with the hard rules (barrel contract, line width, relative imports inside lib/src/, private-member commenting, changelog labels, no InheritedWidget lookup in initState, named boolean parameters, file_names, directives_ordering).
• Philosophy — layering (stream_core → stream_core_flutter), avoiding secret state, error-message quality, streams as primary reactive primitive for real-time data.
• Repository structure — monorepo layout, Melos-managed deps, generated code, and — critically — the public barrel contract (core.dart vs chat.dart, melos run check:barrels enforcement).
• Documentation — dartdoc conventions, plus repo-specific rules (public docs describe the contract not the implementation, no Flutter internals in comments, private members use // not ///).
• Coding patterns — asserts (no message required here — prefer_asserts_with_message is disabled), dispose lifecycle, equality boilerplates, dot shorthands, strict-inference / strict-raw-types implications, no InheritedWidget lookup in initState, early-return pattern, relative-imports convention.
• Testing — self-contained tests, mocktail, alchemist golden tests, test/components/<name>/goldens/{ci,macos} layout. Points at TESTING.md for writing-style guidance.
• Widgets, themes, and design system — the component/theme/golden/Widgetbook 4-artifact rule, the theme hierarchy (primitives → semantics → components → tokens), @themeGen for component themes vs @ThemeExtensions(constructor: 'raw', ...) for the root StreamTheme, defaults in widget build (Flutter's AppBar/TabBar pattern), icon generation from SVGs.
• Naming, comments, formatting, commits/PRs/changelogs — the usual sections, with rules that match verified repo practice.

What's in TESTING.md

Four principles from Flutter's Writing-Effective-Tests with Stream-Core-flavoured examples using StreamAvatar, StreamAvatarSize, StreamMessageBubble:

1. Name tests based on the behavior being tested, not the object.
2. One behavior per test.
3. Only include relevant details — extract setup into named helpers.
4. Optimize for comprehension — separate "the thing under test" from "the actions on it".
5. Bonus: golden tests are behavioural tests too — name them after the variant being pinned, not the widget.

Divergences from Flutter's guide

Called out inline every time; the notable ones:

• Relative imports inside lib/src/ — this repo has always_use_package_imports: false. Flutter's guide requires package: imports; we prefer relative paths inside a package for refactor safety.
• Bare // ignore: directives and bare // TODO: (with optional category tag like TODO(localize):, not GitHub handles) match repo practice.
• Assert messages not required — prefer_asserts_with_message is disabled here.
• Streams as the primary reactive primitive for WS/RxDart pipelines. Flutter recommends Listenable; that reasoning doesn't apply to a real-time transport layer.
• Private members use //, not ///.
• Line width 120, not 100.

Verified against the repo before merging

• Root theme class is StreamTheme (extends ThemeExtension<StreamTheme>) — there is no StreamThemeData. Fixed in the guide.
• Component categories list matches lib/src/components/ (17 categories, not the 10 previously in CLAUDE.md).
• Widgetbook use-cases live under apps/design_system_gallery/lib/components/, not /use_cases/.
• StreamAvatarSize enum values (xs, sm, md, lg, xl, xxl) — the switch example uses correct radii.
• No BetterStreamBuilder reference (that class lives in stream-chat-flutter, not here).
• TESTING.md examples use only real APIs (StreamAvatar, StreamAvatarSize, StreamMessageBubble, StreamWsClient).
• Changelog labels (### ✨ Features, ### 🐛 Bug Fixes, ### 🛑 Breaking / Removals) match current package changelogs, with grandfathered ### 🐞 Fixed / ### 💥 BREAKING CHANGES noted.
• Theming section describes @themeGen for component themes and @ThemeExtensions(constructor: 'raw', ...) for the root — verified against stream_theme.dart and stream_avatar_theme.dart.
• Extension-methods section distinguishes domain-typed collections (fine) from unconstrained-type extensions (avoid new ones).

Test plan

• Skim the "Quick rules" section — every bullet links to its full section below.
• Read TESTING.md end-to-end — it's short (~210 lines).
• Verify divergences from Flutter's guide match your read of current repo practice.
• Confirm the barrel-contract wording matches your check_barrels.yaml intent.
• Suggest anything missing (a rule you rely on that isn't captured, an example that would help).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a repository style guide covering coding conventions, API boundaries, testing expectations, formatting rules, and component implementation standards.
  • Expanded testing guidance with clearer advice on writing behavior-focused, readable, and maintainable tests.
  • Updated the main contributor guidance to point readers to the style guide as the primary source for repository conventions.

[coderabbitai]

Warning

Review limit reached

@xsahil03x, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 9 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 45835c41-2ca5-463e-b1b4-fef4df74ed1f

📥 Commits

Reviewing files that changed from the base of the PR and between a3de967 and a244a26.

📒 Files selected for processing (1)

• STYLE_GUIDE.md

📝 Walkthrough

Walkthrough

Adds documentation only: CLAUDE.md gains a pointer to a new STYLE_GUIDE.md; STYLE_GUIDE.md introduces a comprehensive Dart/Flutter/Widgetbook style guide for the monorepo covering API design, coding, testing, naming, formatting, and design-system conventions; TESTING.md adds a guide on writing effective tests.

Changes

Documentation additions

Layer / File(s)	Summary
Style guide pointer CLAUDE.md	Adds an instruction directing readers to consult STYLE_GUIDE.md before writing or reviewing code.
Style guide intro and API design philosophy STYLE_GUIDE.md	Introduces guide intent/audience, a quick-rules checklist, and API design philosophy (lazy programming, test-first, layering, workarounds, abandonware/deprecation, licensing).
Repo structure, barrels, and dartdoc rules STYLE_GUIDE.md	Defines monorepo/barrel conventions, Melos dependency management, generated code handling, and dartdoc documentation requirements.
Coding patterns and testing/naming conventions STYLE_GUIDE.md	Covers lint-enforced coding patterns (asserts, typing, equality, dispose, Result<T> error handling) plus testing and naming/spelling conventions.
Comment style and formatting rules STYLE_GUIDE.md	Defines comment conventions and formatting/process standards (Melos formatting, member ordering, braces, double literals).
Design-system requirements and PR/changelog process STYLE_GUIDE.md	Details design-system component/theme/icon requirements, PR title conventions, changelog formatting, and doc navigation pointers.
TESTING.md test-writing guide TESTING.md	Adds a guide covering test naming by behavior, one-behavior-per-test, extracting setup helpers, readability structuring, and golden test conventions.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed, but it omits required template sections like Linear, GitHub Issue, CLA checkboxes, and Screenshots/Videos.	Add the missing template sections and fill in Linear/GitHub Issue, CLA status, testing details, and screenshots/videos if applicable.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the two new documentation files and that they are adapted from Flutter's guides.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/style-guide

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.26%. Comparing base (31ca84f) to head (a244a26).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #125   +/-   ##
=======================================
  Coverage   37.26%   37.26%           
=======================================
  Files         175      175           
  Lines        6986     6986           
=======================================
  Hits         2603     2603           
  Misses       4383     4383           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

{}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

STYLE_GUIDE.md (1)

253-257: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the public logger export in the style guide packages/stream_core/lib/stream_core.dart already exports src/logger.dart, so point readers at package:stream_core/stream_core.dart instead of the internal stream_core/src/logger/ path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@STYLE_GUIDE.md` around lines 253 - 257, The style guide currently points
readers to the internal logger path, but the public export already exists.
Update the guidance in STYLE_GUIDE.md to reference the Logger via
package:stream_core/stream_core.dart instead of stream_core/src/logger/, and
keep the note about using debugPrint in stream_core_flutter where appropriate.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@STYLE_GUIDE.md`:
- Around line 1117-1130: The deliverables checklist is inconsistent because it
enumerates five required items but ends with “any of the four.” Update the
summary in STYLE_GUIDE.md to say “any of the five” so it matches the listed
deliverables (Widget file, Theme file, Golden test, Widgetbook use-case, and
Barrel export).

---

Nitpick comments:
In `@STYLE_GUIDE.md`:
- Around line 253-257: The style guide currently points readers to the internal
logger path, but the public export already exists. Update the guidance in
STYLE_GUIDE.md to reference the Logger via package:stream_core/stream_core.dart
instead of stream_core/src/logger/, and keep the note about using debugPrint in
stream_core_flutter where appropriate.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14be598c-ffda-4ad9-8419-54928c9b02a3

📥 Commits

Reviewing files that changed from the base of the PR and between 31ca84f and d70a1da.

📒 Files selected for processing (3)

• CLAUDE.md
• STYLE_GUIDE.md
• TESTING.md

[coderabbitai]

♻️ Duplicate comments (1)

STYLE_GUIDE.md (1)

1153-1174: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Update the checklist count to five.

The list now has five required deliverables, so “any of the four” is stale and makes the policy inconsistent.

Suggested fix

- Missing any of the four is a review-blocker.
+ Missing any of the five is a review-blocker.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@STYLE_GUIDE.md` around lines 1153 - 1174, The checklist in STYLE_GUIDE.md is
outdated and still says “any of the four” even though the required deliverables
now total five. Update the closing policy text in the component deliverables
list to reflect five items, and keep the wording consistent with the existing
bullets around Widget file, Theme file, tests, Widgetbook use-case, and Barrel
export so the review-blocker rule matches the current requirements.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@STYLE_GUIDE.md`:
- Around line 1153-1174: The checklist in STYLE_GUIDE.md is outdated and still
says “any of the four” even though the required deliverables now total five.
Update the closing policy text in the component deliverables list to reflect
five items, and keep the wording consistent with the existing bullets around
Widget file, Theme file, tests, Widgetbook use-case, and Barrel export so the
review-blocker rule matches the current requirements.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0aaaf98e-d6c5-4eeb-99e8-b167cdc343c1

📥 Commits

Reviewing files that changed from the base of the PR and between d70a1da and a3de967.

📒 Files selected for processing (1)

• STYLE_GUIDE.md