signal-bot/signal_bot/unknown.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""What to do with a "!" word the registry does not recognise.

Until now the answer was "nothing at all", which conflated three unrelated
situations the dispatcher could not tell apart: a word nobody registered, a
word registered to some *other* group, and a real trigger with junk after it.
The first two deserve an answer. The third is "!kot ładny", which has always
been silent and stays silent -- a bot that pipes up every time somebody adds
a word to a working command is a bot people mute.

Silence is decided by the *global* question -- does anything, in any group,
claim this word -- and the near-miss search then reads only the triggers live
in the asking group. Both halves are needed. The first keeps the album's
triggers, which are real people's names, from being echoed or recorded in a
group that has no album; the second keeps them out of a suggestion.
"""

from __future__ import annotations

import logging
import re
from dataclasses import dataclass
from typing import TYPE_CHECKING, Final

from signal_bot.folding import fold
from signal_bot.nearest import nearest
from signal_bot.quoting import quote_of

if TYPE_CHECKING:
    from collections.abc import Mapping

    from signal_bot.models import IncomingMessage
    from signal_bot.registry import Command, CommandRegistry
    from signal_bot.store import Store
    from signal_bot.transport_base import Transport

logger = logging.getLogger(__name__)

# What may count as a mistyped command. Anything else -- a bare "!", "!!",
# "!?", an emoji, a pasted paragraph -- is ordinary punctuation and is
# ignored entirely: no reply and no row.
#
# Digits are in the class on purpose. fold() maps 0134578 onto letters but
# leaves 2, 6 and 9 alone, so "!rok2" really does arrive with a digit in it,
# and a letters-only guard would swallow a perfectly plausible typo.
WORD_SHAPE: Final = re.compile(r"^![a-z0-9_]{2,32}$")

# The spelling every one of these messages points people at. It lives here
# rather than in suggest_command because that module needs WORD_SHAPE from
# this one, and two modules importing each other is not a seam. A test
# pins it against aliases.json so the two cannot drift.
SUGGEST_PRIMARY: Final = "!zaproponuj"

DID_YOU_MEAN: Final = "Nie znam {word}. Chodziło o {primary}?"
NO_MATCH: Final = "Nie znam {word}. Napisz {hint} {word} <co ma robić>, a zapiszę pomysł."


@dataclass(frozen=True, slots=True)
class Unknown:
    """A "!" word nothing claims here, and the message that carried it."""

    word: str
    body: str


def unknown_in(text: str | None, registry: CommandRegistry) -> Unknown | None:
    """Read an unrecognised command out of a message, if there is one.

    Args:
        text: The raw message body.
        registry: The command registry, asked the *global* question.

    Returns:
        The unrecognised word and the message it came in, or None when the
        message is not a command attempt at all.
    """
    if not text:
        return None
    words = text.split()
    if not words:
        return None
    word = fold(words[0])
    if WORD_SHAPE.match(word) is None:
        return None
    # Claimed anywhere at all, not merely here -- ``resolve`` with no group
    # is the same question pack_add asks before minting a label. This one
    # check covers two very different cases:
    #
    #   "!kot ładny"  a real trigger with words after it. resolve_with_args
    #                 already decided that means nothing for a command
    #                 taking no arguments, and it is not this file's to
    #                 revisit.
    #   "!alfa"       an album command, in a group that has no album. The
    #                 album's triggers are real people's names, and
    #                 pack_scoping says it out loud: "a refusal would itself
    #                 announce that the album exists". Answering here would
    #                 announce it, and recording the row would put the name
    #                 in the database and on the management page.
    if registry.resolve(word) is not None:
        return None
    return Unknown(word=word, body=text)


def reply_for(word: str, live: Mapping[str, Command]) -> str:
    """What to say about one unrecognised word.

    The suggestion prints ``Command.primary`` -- the same spelling !pomoc
    shows -- rather than the folded trigger it matched, which is a skeleton
    with the diacritics stripped off and reads as a second typo.
    """
    hit = nearest(word, live)
    if hit is None:
        return NO_MATCH.format(word=word, hint=SUGGEST_PRIMARY)
    return DID_YOU_MEAN.format(word=word, primary=live[hit].primary)


async def answer_unknown(
    *,
    message: IncomingMessage,
    group_id: str,
    registry: CommandRegistry,
    store: Store,
    transport: Transport,
) -> None:
    """Remember one unrecognised command and answer it, or do neither."""
    unknown = unknown_in(message.text, registry)
    if unknown is None:
        return
    live = registry.triggers_in(group_id)
    # No word and no body in the log line. A misspelled name is still a
    # name, log lines reach CI output, and the database is the record.
    logger.debug("unrecognised command in %s", group_id)
    store.suggestions.record_unknown(group_id, unknown.word, unknown.body, message.timestamp)
    await transport.send_text(reply_for(unknown.word, live), group_id, quote_of(message))