fix: consistent user mention formatting with @username preference

- Update get_user_mention() to accept User | Chat objects
- Add optional username param to get_user_mention_by_id()
- Normalize usernames with lstrip('@') to prevent @@Prefix
- Use get_user_mention(chat) in verify.py and check.py handlers
  for public-facing messages (clearance, warn callbacks)

This ensures verification success messages show '@username' instead
of just the first name when username is available.

Tests:
- Add 10 new tests for Chat objects and username normalization
- Add explicit test for clearance message format
- Update README with current stats: 404 tests, 99% coverage

Author: rezhajulio

README.md

@@ -150,9 +150,9 @@ uv run pytest -v
 ### Test Coverage
 
 The project maintains comprehensive test coverage:
-- **Coverage**: 100% (1,204 statements)
-- **Tests**: 345 total
-- **Pass Rate**: 100% (345/345 passed)
+- **Coverage**: 99% (1,216 statements)
+- **Tests**: 404 total
+- **Pass Rate**: 100% (404/404 passed)
 - **All modules**: 100% coverage including JobQueue scheduler integration, captcha verification, and anti-spam enforcement
   - Services: `bot_info.py` (100%), `scheduler.py` (100%), `user_checker.py` (100%), `telegram_utils.py` (100%), `captcha_recovery.py` (100%)
   - Handlers: `anti_spam.py` (100%), `captcha.py` (100%), `check.py` (100%), `dm.py` (100%), `message.py` (100%), `topic_guard.py` (100%), `verify.py` (100%)

src/bot/handlers/check.py

@@ -23,7 +23,11 @@
     MISSING_ITEMS_SEPARATOR,
 )
 from bot.database.service import get_database
-from bot.services.telegram_utils import extract_forwarded_user, get_user_mention_by_id
+from bot.services.telegram_utils import (
+    extract_forwarded_user,
+    get_user_mention,
+    get_user_mention_by_id,
+)
 from bot.services.user_checker import check_user_profile
 
 logger = logging.getLogger(__name__)
@@ -248,7 +252,7 @@ async def handle_warn_callback(
     try:
         # Get user info for mention
         chat = await context.bot.get_chat(target_user_id)
-        user_mention = get_user_mention_by_id(target_user_id, chat.full_name or f"User {target_user_id}")
+        user_mention = get_user_mention(chat)
 
         # Send warning to group
         warn_message = ADMIN_WARN_USER_MESSAGE.format(

src/bot/handlers/verify.py

@@ -15,7 +15,7 @@
 from bot.config import Settings, get_settings
 from bot.constants import VERIFICATION_CLEARANCE_MESSAGE
 from bot.database.service import DatabaseService, get_database
-from bot.services.telegram_utils import get_user_mention_by_id, unrestrict_user
+from bot.services.telegram_utils import get_user_mention, unrestrict_user
 
 logger = logging.getLogger(__name__)
 
@@ -62,7 +62,7 @@ async def verify_user(
     if deleted_count > 0:
         # Get user info for proper mention
         user_info = await bot.get_chat(target_user_id)
-        user_mention = get_user_mention_by_id(target_user_id, user_info.full_name)
+        user_mention = get_user_mention(user_info)
 
         # Send clearance message to warning topic
         clearance_message = VERIFICATION_CLEARANCE_MESSAGE.format(

src/bot/services/telegram_utils.py

@@ -7,47 +7,54 @@
 
 import logging
 
-from telegram import Bot, Message, User
+from telegram import Bot, Chat, Message, User
 from telegram.constants import ChatMemberStatus
 from telegram.error import BadRequest, Forbidden
 from telegram.helpers import mention_markdown
 
 logger = logging.getLogger(__name__)
 
 
-def get_user_mention(user: User) -> str:
+def get_user_mention(user: User | Chat) -> str:
     """
-    Get a formatted mention string for a user.
+    Get a formatted mention string for a user or chat.
 
-    Returns `@username` if the user has a username, otherwise returns
-    a markdown mention using the user's full name and ID.
+    Returns `@username` if the user/chat has a username, otherwise returns
+    a markdown mention using the full name and ID.
 
     Args:
-        user: Telegram User object.
+        user: Telegram User or Chat object.
 
     Returns:
         str: Formatted user mention (either @username or markdown mention).
     """
     return (
-        f"@{user.username}"
+        f"@{user.username.lstrip('@')}"
         if user.username
         else mention_markdown(user.id, user.full_name, version=1)
     )
 
 
-def get_user_mention_by_id(user_id: int, user_full_name: str) -> str:
+def get_user_mention_by_id(
+    user_id: int,
+    user_full_name: str,
+    username: str | None = None,
+) -> str:
     """
-    Get a formatted markdown mention for a user by ID and name.
+    Get a formatted mention for a user by ID and name.
 
     Used when only user ID and full name are available (not a full User object).
 
     Args:
         user_id: Telegram user ID.
         user_full_name: User's full name.
+        username: Optional username to prefer @username format.
 
     Returns:
-        str: Markdown mention string.
+        str: Formatted mention string.
     """
+    if username:
+        return f"@{username.lstrip('@')}"
     return mention_markdown(user_id, user_full_name, version=1)
 
 

tests/test_check.py

@@ -438,14 +438,15 @@ async def test_warn_callback_success_missing_photo_only(
 
         mock_chat = MagicMock()
         mock_chat.full_name = "Test User"
+        mock_chat.username = "testuser"
         mock_context.bot.get_chat.return_value = mock_chat
 
         with patch("bot.handlers.check.get_settings", return_value=mock_settings):
             await handle_warn_callback(update, mock_context)
 
         send_call_args = mock_context.bot.send_message.call_args
         assert "foto profil publik" in send_call_args.kwargs["text"]
-        assert "username" not in send_call_args.kwargs["text"]
+        assert "@testuser" in send_call_args.kwargs["text"]
 
     async def test_warn_callback_invalid_data(self, mock_context):
         """Invalid callback data shows error."""

tests/test_telegram_utils.py

@@ -1,7 +1,7 @@
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from telegram import User
+from telegram import Chat, User
 from telegram.error import BadRequest, Forbidden
 
 from bot.services.telegram_utils import (
@@ -97,6 +97,67 @@ def test_get_user_mention_long_full_name(self, mock_mention_markdown):
         mock_mention_markdown.assert_called_once_with(777888, "A" * 100, version=1)
         assert result == f"[{'A' * 100}](tg://user?id=777888)"
 
+    def test_get_user_mention_with_prefixed_username(self):
+        """Test that username with @ prefix is normalized."""
+        user = MagicMock(spec=User)
+        user.username = "@already_prefixed"
+        user.id = 123456
+        user.full_name = "Test User"
+
+        result = get_user_mention(user)
+
+        assert result == "@already_prefixed"
+
+    def test_get_user_mention_chat_with_username(self):
+        """Test getting mention for Chat object with username."""
+        chat = MagicMock(spec=Chat)
+        chat.username = "john_doe"
+        chat.id = 123456
+        chat.full_name = "John Doe"
+
+        result = get_user_mention(chat)
+
+        assert result == "@john_doe"
+
+    def test_get_user_mention_chat_with_prefixed_username(self):
+        """Test that Chat with @ prefixed username is normalized."""
+        chat = MagicMock(spec=Chat)
+        chat.username = "@prefixed_chat"
+        chat.id = 123456
+        chat.full_name = "Prefixed Chat"
+
+        result = get_user_mention(chat)
+
+        assert result == "@prefixed_chat"
+
+    @patch("bot.services.telegram_utils.mention_markdown")
+    def test_get_user_mention_chat_without_username(self, mock_mention_markdown):
+        """Test getting mention for Chat object without username."""
+        chat = MagicMock(spec=Chat)
+        chat.username = None
+        chat.id = 123456
+        chat.full_name = "Jane Smith"
+        mock_mention_markdown.return_value = "[Jane Smith](tg://user?id=123456)"
+
+        result = get_user_mention(chat)
+
+        mock_mention_markdown.assert_called_once_with(123456, "Jane Smith", version=1)
+        assert result == "[Jane Smith](tg://user?id=123456)"
+
+    @patch("bot.services.telegram_utils.mention_markdown")
+    def test_get_user_mention_chat_empty_username(self, mock_mention_markdown):
+        """Test getting mention for Chat object with empty string username."""
+        chat = MagicMock(spec=Chat)
+        chat.username = ""
+        chat.id = 987654
+        chat.full_name = "Jane Smith"
+        mock_mention_markdown.return_value = "[Jane Smith](tg://user?id=987654)"
+
+        result = get_user_mention(chat)
+
+        mock_mention_markdown.assert_called_once_with(987654, "Jane Smith", version=1)
+        assert result == "[Jane Smith](tg://user?id=987654)"
+
 
 class TestGetUserMentionById:
     @patch("bot.services.telegram_utils.mention_markdown")
@@ -160,6 +221,44 @@ def test_get_user_mention_by_id_single_character_name(self, mock_mention_markdow
         mock_mention_markdown.assert_called_once_with(777888, "A", version=1)
         assert result == "[A](tg://user?id=777888)"
 
+    def test_get_user_mention_by_id_with_username(self):
+        """Test mention by ID with username provided returns @username."""
+        result = get_user_mention_by_id(123456, "John Doe", username="johndoe")
+
+        assert result == "@johndoe"
+
+    def test_get_user_mention_by_id_with_username_special_chars(self):
+        """Test mention by ID with username containing underscores."""
+        result = get_user_mention_by_id(123456, "John Doe", username="john_doe_123")
+
+        assert result == "@john_doe_123"
+
+    def test_get_user_mention_by_id_with_prefixed_username(self):
+        """Test that username with @ prefix is normalized."""
+        result = get_user_mention_by_id(123456, "Test User", username="@prefixed")
+
+        assert result == "@prefixed"
+
+    @patch("bot.services.telegram_utils.mention_markdown")
+    def test_get_user_mention_by_id_with_none_username(self, mock_mention_markdown):
+        """Test mention by ID with explicit None username."""
+        mock_mention_markdown.return_value = "[John Doe](tg://user?id=123456)"
+
+        result = get_user_mention_by_id(123456, "John Doe", username=None)
+
+        mock_mention_markdown.assert_called_once_with(123456, "John Doe", version=1)
+        assert result == "[John Doe](tg://user?id=123456)"
+
+    @patch("bot.services.telegram_utils.mention_markdown")
+    def test_get_user_mention_by_id_with_empty_username(self, mock_mention_markdown):
+        """Test mention by ID with empty string username falls back to markdown."""
+        mock_mention_markdown.return_value = "[John Doe](tg://user?id=123456)"
+
+        result = get_user_mention_by_id(123456, "John Doe", username="")
+
+        mock_mention_markdown.assert_called_once_with(123456, "John Doe", version=1)
+        assert result == "[John Doe](tg://user?id=123456)"
+
 
 class TestUnrestrictUser:
     async def test_unrestrict_user_basic(self, mock_bot):

tests/test_verify_handler.py

@@ -56,6 +56,7 @@ def mock_context():
     mock_permissions.can_pin_messages = False
     mock_chat.permissions = mock_permissions
     mock_chat.full_name = "Test User"
+    mock_chat.username = "testuser"
     context.bot.get_chat.return_value = mock_chat
 
     context.bot_data = {"admin_ids": [12345]}
@@ -285,6 +286,45 @@ class MockSettings:
         new_warning = db.get_or_create_user_warning(target_user_id, MockSettings.group_id)
         assert new_warning.message_count == 1  # Fresh start
 
+    async def test_verify_sends_clearance_message_when_warnings_deleted(
+        self, mock_update, mock_context, temp_db, monkeypatch
+    ):
+        """Test that clearance message is sent to warning topic when user with warnings is verified."""
+        class MockSettings:
+            group_id = -1001234567890
+            warning_topic_id = 12345
+            telegram_bot_token = "fake_token"
+
+        monkeypatch.setattr("bot.handlers.verify.get_settings", lambda: MockSettings())
+
+        target_user_id = 77777777
+        db = get_database()
+
+        # Seed a warning for the target user
+        db.get_or_create_user_warning(target_user_id, MockSettings.group_id)
+        db.increment_message_count(target_user_id, MockSettings.group_id)
+
+        # Mock get_chat to return a user with username
+        mock_user_chat = MagicMock()
+        mock_user_chat.username = "verified_user"
+        mock_user_chat.full_name = "Verified User"
+
+        # First call is for group permissions, second call is for user info
+        mock_group_chat = MagicMock()
+        mock_group_chat.permissions = MagicMock()
+        mock_context.bot.get_chat.side_effect = [mock_group_chat, mock_user_chat]
+
+        mock_context.args = [str(target_user_id)]
+        await handle_verify_command(mock_update, mock_context)
+
+        # Verify send_message was called with correct clearance message
+        mock_context.bot.send_message.assert_called_once()
+        call_kwargs = mock_context.bot.send_message.call_args.kwargs
+        assert call_kwargs["chat_id"] == MockSettings.group_id
+        assert call_kwargs["message_thread_id"] == MockSettings.warning_topic_id
+        assert "@verified_user" in call_kwargs["text"]
+        assert call_kwargs["parse_mode"] == "Markdown"
+
     async def test_verify_handles_non_restricted_user_gracefully(
         self, mock_update, mock_context, temp_db, monkeypatch
     ):
@@ -348,7 +388,7 @@ class MockSettings:
         assert call_args.kwargs["message_thread_id"] == MockSettings.warning_topic_id
         assert call_args.kwargs["parse_mode"] == "Markdown"
         # Check the message contains user mention
-        assert "Test User" in call_args.kwargs["text"] or str(target_user_id) in call_args.kwargs["text"]
+        assert "@testuser" in call_args.kwargs["text"]
 
     async def test_verify_without_warnings_no_notification(
         self, mock_update, mock_context, temp_db, monkeypatch