fix: always include m.mentions on outgoing messages

[kamor-famedly]

Closes #2302

Summary by CodeRabbit

• New Features

  • Messages now generate and include mention metadata to accurately identify and track mentioned users and rooms
  • Mention detection improved with boundary checking to prevent false matches
  • Commands now support toggling automatic mention detection behavior

• Bug Fixes

  • Legacy mention notification rules now properly suppressed when modern mention metadata is present

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 55.77%. Comparing base (f10161c) to head (62c6d4d).
⚠️ Report is 23 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2330      +/-   ##
==========================================
+ Coverage   55.32%   55.77%   +0.45%     
==========================================
  Files         160      160              
  Lines       19854    19868      +14     
==========================================
+ Hits        10984    11082      +98     
+ Misses       8870     8786      -84     

Files with missing lines	Coverage Δ
lib/src/room.dart	76.32% <100.00%> (+0.06%)	⬆️
lib/src/utils/commands_extension.dart	65.21% <100.00%> (+0.38%)	⬆️
lib/src/utils/pushrule_evaluator.dart	96.70% <100.00%> (+0.15%)	⬆️

... and 14 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f10161c...62c6d4d. Read the comment docs.

[td-famedly]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e419f05-3cb7-41df-ab09-b3caaf058be5

📥 Commits

Reviewing files that changed from the base of the PR and between f10161c and 62c6d4d.

📒 Files selected for processing (6)

• lib/src/room.dart
• lib/src/utils/commands_extension.dart
• lib/src/utils/pushrule_evaluator.dart
• test/commands_test.dart
• test/pushevaluator_test.dart
• test/room_test.dart

---

📝 Walkthrough

Walkthrough

This PR implements m.mentions metadata support for outgoing Matrix messages, addressing spec v1.17 requirements. A regex-based mention detector identifies candidate mentions in message bodies, builds corresponding metadata structures, and integrates with text sending, generic message sending, and command handlers. Legacy push rules are suppressed when modern metadata is present to prevent duplicate notifications.

Changes

m.mentions metadata support

Layer / File(s)	Summary
Mention detection logic and metadata builders lib/src/room.dart	New _mentionCandidateRegex detects user mentions, MXID forms, and @room syntax. Private _isValidMentionStart and _mentionsMetadataForMessage collect candidates, treat @room specially, include replied-to users, deduplicate, and exclude the sender from mention structures.
Text and generic message sending integration lib/src/room.dart	sendTextEvent passes addMentions flag to command parsing and sets m.mentions from the detection helper. sendEvent ensures empty m.mentions is present for all message events with a body string to prevent legacy mention scanning.
Command handler mention support lib/src/utils/commands_extension.dart	parseAndRunCommand accepts addMentions parameter and forwards it to CommandArgs. Default /send, /me, and /plain commands pass addMentions through to room.sendTextEvent for per-command control.
Push rule legacy mention suppression lib/src/utils/pushrule_evaluator.dart	New _legacyMentionRuleIds set lists pre-v1.17 rule IDs. _OptimizedRules stores ruleId and defaultRule to enable legacy detection. PushruleEvaluator.match skips legacy mention rules when m.mentions metadata is present.
Room send and mention parsing tests test/room_test.dart	New and updated tests verify empty m.mentions is backfilled for messages with body, existing metadata is preserved, user mentions are detected via display-name form, mention boundaries enforce start/whitespace rules, invalid candidates (email-like, double-@) are rejected, and disabling mentions yields empty metadata.
Command and push rule evaluation tests test/commands_test.dart, test/pushevaluator_test.dart	Command tests verify m.mentions presence in sent payloads for /send, /me, /plain, and thread operations, with user IDs populated when replies target users. New push rule test validates legacy rules stop matching once m.mentions is present and modern rules match based on metadata contents.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objective: ensuring m.mentions metadata is always included on outgoing messages, which directly matches the primary changeset focus.
Linked Issues check	✅ Passed	The PR successfully implements the requirements from issue #2302: m.mentions is now always included on outgoing events, and legacy mention-related push rules are suppressed when m.mentions is present.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the linked issue objectives: mention metadata implementation, command extension updates for toggle support, and push rule suppression for legacy mentions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch khalil/outgoing-message-mentions-metadata

---

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