Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

10.5 KB
Raw Blame
"""Pure rule evaluation engine — no DB access."""
import re
import unicodedata
import uuid
from collections.abc import Collection
from datetime import date, datetime
from decimal import Decimal, InvalidOperation
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from app.models.transaction import Transaction


def _strip_accents(text: str) -> str:
    """Remove diacritics (accents), preserving case."""
    nfkd = unicodedata.normalize("NFKD", text)
    return "".join(c for c in nfkd if not unicodedata.combining(c))


def compile_rule_regex(pattern: str) -> re.Pattern[str]:
    """Compile a regex using Securo's runtime normalization and safety policy."""
    effective_pattern = _strip_accents(pattern)
    try:
        compiled = re.compile(effective_pattern, re.IGNORECASE)
    except re.error as exc:
        raise ValueError("Invalid regular expression") from exc
    if compiled.search("") is not None:
        raise ValueError("Regular expression must not match an empty string")
    return compiled


def _normalize(text: str) -> str:
    """Normalize text: uppercase and remove diacritics (accents)."""
    return _strip_accents(text.upper())


def _to_decimal(val) -> Decimal:
    try:
        return Decimal(str(val))
    except InvalidOperation:
        return Decimal("0")


def _signed_amount(tx: "Transaction", raw) -> Decimal:
    """The amount as a condition compares it: credits positive, debits negative.

    Amounts are stored positive with the direction in `type`, so an unsigned
    comparison sees every transaction as positive. The sign is what lets
    `amount > 0` select income and `amount < 0` expenses. The magnitude is
    taken first because a row saved with a negative amount (the manual API
    does not reject one) must follow the same contract: the sign comes from
    `type` alone.
    """
    amount = abs(_to_decimal(raw))
    if getattr(tx, "type", None) == "debit":
        amount = -amount
    return amount


def _to_date(val) -> date | None:
    if isinstance(val, datetime):
        return val.date()
    if isinstance(val, date):
        return val
    if isinstance(val, str):
        try:
            return date.fromisoformat(val)
        except ValueError:
            return None
    return None


def _match_condition(condition: dict, tx: "Transaction") -> bool:
    field = condition.get("field", "")
    op = condition.get("op", "")
    value = condition.get("value")

    tx_val = getattr(tx, field, None)

    # A blank value matches everything: "" is a substring of any string, every
    # string starts/ends with it, an empty regex always matches, and numeric
    # comparisons fall back to 0. Creation now rejects these, but rules saved
    # before that validation existed are still in users' databases — refuse to
    # match rather than recategorizing their whole ledger. Explicit 0/False
    # are real values and pass through.
    if value is None or (isinstance(value, str) and not value.strip()):
        return False

    # String operators
    if op in ("contains", "not_contains", "starts_with", "ends_with", "equals", "not_equals", "regex"):
        tx_str = _normalize(str(tx_val or ""))
        val_str = _normalize(str(value or ""))

        if op == "contains":
            return val_str in tx_str
        if op == "not_contains":
            return val_str not in tx_str
        if op == "starts_with":
            return tx_str.startswith(val_str)
        if op == "ends_with":
            return tx_str.endswith(val_str)
        if op == "equals":
            # Amounts are stored with a fixed scale (100.00) while the rule
            # form submits the number as typed (100): comparing their string
            # forms would never agree. Compare numerically when both sides
            # parse, and fall back to text when either does not. The
            # comparison is signed: a debit of 100.00 is -100.
            if field == "amount":
                try:
                    return _signed_amount(tx, tx_val) == Decimal(str(value))
                except InvalidOperation:
                    pass
            return tx_str == val_str
        if op == "not_equals":
            # Signed for the same reason as `equals`: a debit of 100.00 is
            # -100, so it is not equal to the typed 100.
            if field == "amount":
                try:
                    return _signed_amount(tx, tx_val) != Decimal(str(value))
                except InvalidOperation:
                    pass
            return tx_str != val_str
        if op == "regex":
            try:
                # Strip accents from the pattern so it lines up with the
                # normalized text, but keep its case: uppercasing a regex
                # inverts escape classes (\s -> \S, \b -> \B, \d -> \D) and
                # breaks inline flags. Case is already handled by IGNORECASE.
                compiled = compile_rule_regex(str(value or ""))
                return compiled.search(tx_str) is not None
            except ValueError:
                return False

    # Numeric operators
    if op in ("gt", "gte", "lt", "lte"):
        if field == "date":
            tx_date = _to_date(tx_val)
            val_date = _to_date(value)
            if tx_date is None or val_date is None:
                return False
            if op == "gt":
                return tx_date > val_date
            if op == "gte":
                return tx_date >= val_date
            if op == "lt":
                return tx_date < val_date
            if op == "lte":
                return tx_date <= val_date

        # Amounts are stored positive with the direction in `type`, so the
        # comparison needs the signed value: `amount > 0` is income and
        # `amount < 0` expenses.
        tx_num = _signed_amount(tx, tx_val) if field == "amount" else _to_decimal(tx_val)
        val_num = _to_decimal(value)
        if op == "gt":
            return tx_num > val_num
        if op == "gte":
            return tx_num >= val_num
        if op == "lt":
            return tx_num < val_num
        if op == "lte":
            return tx_num <= val_num

    return False


def _is_group(node: dict) -> bool:
    """A condition list entry is a group when it carries its own condition list."""
    return isinstance(node, dict) and isinstance(node.get("conditions"), list)


def _match_group(group: dict, tx: "Transaction") -> bool:
    """Evaluate one nested group: its leaves joined by the group's own operator.

    Groups hold leaves only, which caps a rule at two levels. A nested group
    would reach `_match_condition` with no `field`/`op` and evaluate to False;
    creation rejects them, so this only guards hand-edited data.
    """
    conditions = group.get("conditions") or []
    if not conditions:
        return False
    results = [_match_condition(c, tx) for c in conditions]
    if group.get("op") == "or":
        return any(results)
    return all(results)  # "and" is default


def evaluate_conditions(conditions_op: str, conditions: list[dict], tx: "Transaction") -> bool:
    """Return True if the transaction matches the rule's conditions.

    Each entry is either a leaf condition (`field`/`op`/`value`) or a group that
    joins its own leaves with its own operator, letting a rule mix AND and OR —
    e.g. `type is debit AND (description contains UBER OR contains 99POP)`.
    """
    if not conditions:
        return False
    results = [
        _match_group(node, tx) if _is_group(node) else _match_condition(node, tx)
        for node in conditions
    ]
    if conditions_op == "or":
        return any(results)
    return all(results)  # "and" is default


def merge_notes(existing: str | None, incoming: str | None) -> str | None:
    """Combine two note strings the way `append_notes` combines tags.

    Used when an incoming charge is folded into a row that already has notes:
    the existing text is never dropped, the incoming one is only appended when
    it is not already in there.
    """
    incoming = (incoming or "").strip()
    if not incoming:
        return existing
    existing = (existing or "").strip()
    if not existing:
        return incoming
    if incoming in existing:
        return existing
    return f"{existing} {incoming}"


def apply_rule_actions(
    actions: list[dict],
    tx: "Transaction",
    category_already_set: bool,
    *,
    skip_description: bool = False,
    assignable_category_ids: Collection[uuid.UUID] | None = None,
) -> bool:
    """Apply actions in-place and return the updated category-set flag.

    Only a category in `assignable_category_ids` is ever written. A rule that
    names any other one keeps its remaining actions and drops the
    categorization, leaving the transaction uncategorized.

    That covers two cases. A hidden category means the user stopped using it,
    so the pickers no longer offer it and neither should a rule. A category
    that is simply gone means the rule went stale: its id lives inside a JSON
    action with no foreign key behind it, and writing it would fail the insert
    and take the whole import or sync batch with it.

    Passing nothing skips the check, for callers with no workspace at hand.
    """
    for action in actions:
        op = action.get("op")
        value = action.get("value")

        if op == "set_category" and not category_already_set:
            try:
                category_id = uuid.UUID(str(value))
            except (ValueError, AttributeError):
                continue
            if assignable_category_ids is not None and category_id not in assignable_category_ids:
                continue
            tx.category_id = category_id
            category_already_set = True

        elif op == "set_description":
            if skip_description:
                continue
            description = str(value or "").strip()
            if not description or description == tx.description:
                continue
            if getattr(tx, "original_description", None) is None:
                tx.original_description = tx.description
            tx.description = description
            tx.description_is_rule_managed = True

        elif op == "set_payee":
            try:
                tx.payee_id = uuid.UUID(str(value))
            except (ValueError, AttributeError):
                pass

        elif op == "append_notes":
            new_tags = str(value or "").strip()
            if not new_tags:
                continue
            existing = tx.notes or ""
            if new_tags not in existing:
                tx.notes = (existing + " " + new_tags).strip() if existing else new_tags

        elif op == "ignore":
            tx.is_ignored = True

    return category_already_set