"""Shared sync-result-line helpers (phase 187, task 03).

The Sources page's sync result line — the ``fmtSyncResult`` counts line
and the neutral ``"Sync cancelled"`` line the ``#sync-progress`` box
speaks — now trails the run's PEAK-MEMORY clause (`` · peak 1936 MB``),
sourced from ``GET /api/sync/status``'s additive ``rss_peak_mb`` /
``rss_mb`` pair (the 2026-10-15 incident: "how much RAM did that sync
use?" used to mean reading ``systemd`` unit-teardown lines off three
boots; now it is on the page that started the run and in the log).

The clause is per-run DATA, so the suites that pin the OWNER-VISIBLE
counts pin the counts plus an OPTIONAL clause:

* :func:`counts_line` — a Playwright-ready pattern: the exact expected
  line, with `` · peak <N> MB`` allowed at the end (and the whole line
  anchored, so a mutated counts line still fails);
* :func:`strip_peak_clause` — for the suites that compare two runs' or
  two apps' lines byte-for-byte: the memory number belongs to the
  process, not to the KB, so it is not part of a byte-identity contract.

A NULL pair renders NOTHING (``fmtSyncPeakClause``), which is why the
clause is optional rather than required: an idle app, a status that
predates phase 187, and the upload job all settle without it.
"""
from __future__ import annotations

import re

#: The clause sources.js appends (``fmtSyncPeakClause``), as a regex —
#: optional, because a null peak/current pair appends the empty string.
PEAK_CLAUSE = r"(?: · peak \d+ MB)?"

#: The same clause, for a substitution (``strip_peak_clause``): anchored
#: at end of line, so nothing else is ever stripped.
_PEAK_CLAUSE_TAIL = re.compile(r" · peak \d+ MB$")


def counts_line(expected: str | re.Pattern[str]) -> re.Pattern[str]:
    """Match the EXACT ``expected`` sync result line, clause included or
    not — the pin a suite writes when it cares about the counts, not
    about the number of megabytes the run happened to reach.

    ``expected`` is either the literal line (escaped, so the ``·`` and
    the digits mean exactly what they say) or a suite's own shape
    pattern (its anchors are dropped and re-applied around the optional
    clause, so ``^3 added$`` becomes ``^3 added(?: · peak \\d+ MB)?$``).
    """
    if isinstance(expected, re.Pattern):
        body = expected.pattern
        if body.startswith("^"):
            body = body[1:]
        if body.endswith("$"):
            body = body[:-1]
        return re.compile(rf"^{body}{PEAK_CLAUSE}$")
    return re.compile(rf"^{re.escape(expected)}{PEAK_CLAUSE}$")


def strip_peak_clause(text: str) -> str:
    """``text`` without its trailing peak clause (if any) — the
    byte-identity comparison's view of the line."""
    return _PEAK_CLAUSE_TAIL.sub("", text)