steppy-dev 0.3.0__py3-none-any.whl

steppy/testids.py

@@ -0,0 +1,166 @@
+"""Test-id grammar and selector → test-id extraction.
+
+In-app tours store a single test-id value per step, never a CSS selector
+(spec fixed decision 2). Scenarios, however, write free-form Playwright
+selectors. :func:`extract_test_id` decides whether an authored selector *is* a
+test-id in disguise and returns its value, or says precisely why not — with a
+fix-it hint the compiler prints verbatim.
+
+Accepted shapes (``A`` = the configured attribute, ``data-testid`` by default)::
+
+    [A="X"]   [A='X']   [A=X]        a pure test-id
+    tag[A="X"]                        tag-qualified
+    [A="X"] tag                       host + one bare descendant tag, reduced to X:
+                                      clicks/inputs inside the host bubble to it
+
+Everything else — attribute prefix matches, descendant qualifiers, selector
+lists, Playwright engines and ``>>`` chains, ``{{var}}`` ids, ``within:`` and
+``match:`` other than ``first`` — cannot be expressed as one stable test-id.
+
+A stdlib-only leaf (it reuses :func:`steppy.assertions.split_top_level`).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .assertions import split_top_level
+from .tour_spec import TEST_ID_ATTRIBUTE_PATTERN, TEST_ID_PATTERN
+
+DEFAULT_TEST_ID_ATTRIBUTE = "data-testid"
+
+_ENGINE_PREFIXES = ("text=", "css=", "xpath=", "role=", "id=", "internal:", "//", "..")
+
+#: Rejection reason -> (explanation, fix-it hint).
+REASONS: dict[str, tuple[str, str]] = {
+    "within": (
+        "the step is scoped with `within:`, so the test-id alone is not unique",
+        "give the element its own unique test-id in the app, or mark the step `tour: skip`",
+    ),
+    "match": (
+        "the step picks one of several matches with `match:`",
+        "give the element its own unique test-id in the app, or mark the step `tour: skip`",
+    ),
+    "empty": ("the selector is empty", "point the step at a test-id"),
+    "interpolated": (
+        "the test-id is computed at run time ({{var}})",
+        "point the step at a stable test-id, or mark it `tour: skip`",
+    ),
+    "playwright-engine": (
+        "it uses a Playwright selector engine, which the in-app player cannot evaluate",
+        "point the step at a test-id, or mark it `tour: skip`",
+    ),
+    "playwright-chain": (
+        "it is a Playwright `>>` chain",
+        "point the step at a single test-id, or mark it `tour: skip`",
+    ),
+    "selector-list": (
+        "it is a comma-separated selector list",
+        "point the step at a single test-id, or mark it `tour: skip`",
+    ),
+    "partial-match": (
+        "it matches the test-id by prefix/suffix/substring",
+        "point the step at an exact test-id, or mark it `tour: skip`",
+    ),
+    "no-test-id": (
+        "it does not use the test-id attribute",
+        "add a test-id in the app (or set `tours.test_id_attribute`), mark the step `tour: skip`, "
+        "or `tour: keep` to show it as a centred note",
+    ),
+    "qualified-descendant": (
+        "it reaches an element inside the test-id host with a qualified selector",
+        "point the step at the host test-id, add a test-id on the inner element, mark the step `tour: skip`, "
+        "or `tour: keep` to show it as a centred note",
+    ),
+    "invalid-value": (
+        "the test-id value has characters outside [A-Za-z0-9_.:/-] (or is longer than 128)",
+        "rename the test-id in the app",
+    ),
+}
+
+
+@dataclass(frozen=True)
+class TargetExtraction:
+    """Outcome of :func:`extract_test_id`: a test-id, or the reason there is none."""
+
+    test_id: Optional[str] = None
+    reason: Optional[str] = None
+    #: The bare descendant tag the selector was reduced from (``[A="X"] button`` → ``button``).
+    reduced_from: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.test_id is not None
+
+    def explain(self) -> str:
+        """``<explanation> — <hint>`` for a failed extraction (empty when ok)."""
+        if self.ok or self.reason is None:
+            return ""
+        why, hint = REASONS[self.reason]
+        return f"{why} — {hint}"
+
+
+def is_test_id(value: object) -> bool:
+    return isinstance(value, str) and re.fullmatch(TEST_ID_PATTERN, value) is not None
+
+
+def check_test_id_attribute(value: object) -> str:
+    """Validate ``tours.test_id_attribute``; raise ``ValueError`` with the rule otherwise."""
+    if not isinstance(value, str) or re.fullmatch(TEST_ID_ATTRIBUTE_PATTERN, value) is None:
+        raise ValueError(f"test-id attribute {value!r} must match {TEST_ID_ATTRIBUTE_PATTERN} (e.g. 'data-testid')")
+    return value
+
+
+def _shape(attribute: str) -> re.Pattern[str]:
+    a = re.escape(attribute)
+    return re.compile(
+        r"\s*(?P<tag>[A-Za-z][A-Za-z0-9-]*)?"
+        r"\[\s*" + a + r"\s*=\s*"
+        r"(?:\"(?P<dq>[^\"\\]*)\"|'(?P<sq>[^'\\]*)'|(?P<uq>-?[A-Za-z_][A-Za-z0-9_-]*))"
+        r"\s*\]"
+        r"(?:\s+(?P<desc>[A-Za-z][A-Za-z0-9-]*))?\s*"
+    )
+
+
+def extract_test_id(
+    selector: Optional[str],
+    attribute: str = DEFAULT_TEST_ID_ATTRIBUTE,
+    *,
+    within: Optional[str] = None,
+    match: Optional[str] = None,
+) -> TargetExtraction:
+    """Return the single test-id ``selector`` designates, or why it designates none.
+
+    The checks run in a fixed order and the first that applies decides, so the
+    reason a scenario author sees is always the most specific one.
+    """
+    if within:
+        return TargetExtraction(reason="within")
+    if match is not None and str(match).strip().lower() != "first":
+        return TargetExtraction(reason="match")
+    sel = (selector or "").strip()
+    if not sel:
+        return TargetExtraction(reason="empty")
+    if "{{" in sel:
+        return TargetExtraction(reason="interpolated")
+    if sel.startswith(_ENGINE_PREFIXES):
+        return TargetExtraction(reason="playwright-engine")
+    if ">>" in sel:
+        return TargetExtraction(reason="playwright-chain")
+    if len(split_top_level(sel)) > 1:
+        return TargetExtraction(reason="selector-list")
+    if re.search(re.escape(attribute) + r"\s*[\^$*~|]=", sel):
+        return TargetExtraction(reason="partial-match")
+    if not re.search(r"\[\s*" + re.escape(attribute) + r"\s*(?:[\^$*~|]?=|\])", sel):
+        return TargetExtraction(reason="no-test-id")
+    m = _shape(attribute).fullmatch(sel)
+    if m is None:
+        return TargetExtraction(reason="qualified-descendant")
+    value = (
+        m.group("dq") if m.group("dq") is not None else m.group("sq") if m.group("sq") is not None else m.group("uq")
+    )
+    if not is_test_id(value):
+        return TargetExtraction(reason="invalid-value")
+    return TargetExtraction(test_id=value, reduced_from=m.group("desc"))

steppy/totp.py

@@ -0,0 +1,26 @@
+"""Time-based one-time password (TOTP / RFC 6238) — stdlib only (FLAWS §6.2).
+
+Steppy's automated MFA login needs to compute a TOTP code from a shared secret.
+Rather than take a ``pyotp`` dependency, this implements RFC 6238 (HMAC-SHA1,
+30-second window, 6 digits) in ~15 lines of the standard library. That keeps the
+**generated** ``conftest.py.j2`` self-contained: it embeds a byte-identical copy
+of ``_totp_now`` (generated runtime code can't import ``steppy``), so a consumer
+project running MFA logins under ``steppy run`` needs no extra package. The
+``tests/test_totp.py`` guard extracts both copies and asserts they agree, and
+pins ``_totp_now`` against the RFC 6238 test vector.
+"""
+
+import base64
+import hmac
+import hashlib
+import time
+
+
+def _totp_now(secret: str, digits: int = 6, period: int = 30) -> str:
+    """Current TOTP code for a base32 ``secret`` (RFC 6238, HMAC-SHA1)."""
+    key = base64.b32decode(secret.strip().replace(" ", "").upper() + "=" * (-len(secret.strip().replace(" ", "")) % 8))
+    counter = int(time.time()) // period
+    mac = hmac.new(key, counter.to_bytes(8, "big"), hashlib.sha1).digest()
+    offset = mac[-1] & 0x0F
+    code = (int.from_bytes(mac[offset : offset + 4], "big") & 0x7FFFFFFF) % (10**digits)
+    return str(code).zfill(digits)

steppy/tour_spec.py

@@ -0,0 +1,163 @@
+"""The in-app tour data contract, v1: vocabulary, grammars and limits.
+
+Shared by the scenario models (annotation enums), the tours compiler, the
+producer-side contract (:mod:`steppy.contracts.tours`) and — through
+``tests/test_tour_contract_sync.py`` — the TypeScript player, whose
+``packages/player/src/tour/contract.ts`` must hold the very same values. The
+player is the security boundary (it validates every file it loads, bundled or
+remote); the compiler must therefore never emit anything these patterns or
+limits reject, or a tour would fail with ``invalid-data`` in production.
+
+Patterns are written without backslashes so the TypeScript mirror can carry
+them as plain string literals, and are always applied with ``re.fullmatch``
+(Python's ``$`` also matches before a trailing newline).
+
+A stdlib-only leaf: ``models.py`` imports it on the eager CLI path.
+"""
+
+from __future__ import annotations
+
+import re
+
+#: The contract version. A player rejects any other major with
+#: ``schema-unsupported`` instead of guessing.
+TOUR_SCHEMA_VERSION = 1
+ACCEPTED_TOUR_SCHEMA_MAJORS = (1,)
+
+# ── Vocabulary ────────────────────────────────────────────────────────────────
+
+#: How a step advances. ``visible`` waits for the step's target to appear;
+#: ``manual`` waits for the Next button.
+ADVANCE_KINDS = ("click", "input", "change", "visible", "manual")
+#: Advance kinds that need a target element — a targetless (centred) step can
+#: only advance on ``manual``.
+TARGETED_ADVANCE_KINDS = frozenset({"click", "input", "change", "visible"})
+
+PLACEMENTS = ("top", "bottom", "left", "right", "auto")
+
+#: Values of the step-level ``tour:`` annotation.
+STEP_TOUR_MODES = ("skip", "keep")
+
+#: DOM events the overlay dispatches (bubbling, composed). Colon-free on
+#: purpose: Angular templates read ``(a:b)`` as a global event target.
+TOUR_EVENTS = ("tour-start", "tour-step", "tour-complete", "tour-dismiss", "tour-offpath", "tour-error")
+
+#: ``tour-error`` reasons.
+TOUR_ERROR_REASONS = ("target-timeout", "entry-params", "load-failed", "schema-unsupported", "invalid-data")
+
+#: Languages the overlay ships chrome strings for (buttons, progress, generic
+#: hints). Any other tour language shows them in English unless the app sets
+#: the host's ``strings`` — the compiler warns ``chrome-strings-missing``.
+CHROME_STRING_LOCALES = ("en", "fr", "nl", "de")
+
+#: ``part`` names the overlay exposes for ``::part()`` theming. The replay test
+#: helpers locate the bubble and its buttons through these, never through text.
+TOUR_PARTS = (
+    "layer",
+    "spotlight",
+    "bubble",
+    "title",
+    "body",
+    "progress",
+    "button",
+    "primary",
+    "secondary",
+    "next",
+    "close",
+    "skip",
+    "end",
+    "resume",
+    "pill",
+    "guide-link",
+)
+
+#: Attributes the overlay sets on its bubble (``section[part~=bubble]``). The
+#: replay helpers scope the Next button by ``data-step-id`` and read
+#: ``data-state`` to tell an anchored popover from the fallback one.
+ATTR_TOUR_ID = "data-tour-id"
+ATTR_STEP_ID = "data-step-id"
+ATTR_STATE = "data-state"
+ATTR_ADVANCE = "data-advance"
+BUBBLE_STATES = ("shown", "fallback")
+
+# ── Grammars ──────────────────────────────────────────────────────────────────
+
+TEST_ID_PATTERN = r"^[A-Za-z0-9_.:/-]{1,128}$"
+#: Step ids are test-ids or heading slugs, so the same grammar holds.
+STEP_ID_PATTERN = TEST_ID_PATTERN
+TEST_ID_ATTRIBUTE_PATTERN = r"^data-[a-z0-9-]+$"
+TOUR_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
+LAYOUT_NAME_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
+ROLE_PATTERN = r"^[A-Za-z0-9_-]{1,64}$"
+#: Coarse shape only; the compiler additionally runs ``locales.validate_locale_tag``.
+LOCALE_PATTERN = r"^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8}){0,5}$"
+SRI_PATTERN = r"^sha384-[A-Za-z0-9+/]{64}$"
+TOUR_FILE_NAME_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}[.][A-Za-z0-9_-]{1,64}[.]json$"
+#: A base-relative route: ``/`` or ``/seg/:param/...``. Literal segments use the
+#: path-safe RFC 3986 set (percent-encoded otherwise); ``.``/``..`` segments
+#: (``%2e`` counts as a dot, as URL parsers read it) and bad ``%XX`` escapes are
+#: rejected by :func:`is_route`, not by the regex.
+ROUTE_PATTERN = r"^/$|^(?:/(?::[A-Za-z_][A-Za-z0-9_]{0,63}|[A-Za-z0-9._~%!$&()*+,;=@-]{1,128})){1,32}$"
+MEDIA_QUERY_PATTERN = r"^[A-Za-z0-9 :().,<>=/_-]{1,256}$"
+
+# ── Limits (a hostile payload must not be able to freeze the page) ────────────
+
+MAX_TOURS = 500
+MAX_STEPS = 100
+MAX_LOCALES = 32
+MAX_LAYOUTS = 16
+MAX_TITLE_CHARS = 200
+MAX_TEXT_CHARS = 2000
+MAX_ROUTE_CHARS = 512
+MAX_URL_CHARS = 2048
+MAX_MEDIA_QUERY_CHARS = 256
+MAX_TOUR_FILE_BYTES = 262_144
+MAX_MANIFEST_BYTES = 1_048_576
+
+# Reserved on Windows for the basename *before* the extension, so `con.en.json`
+# is un-creatable just as `con` is. Same list as `exclusive._WINDOWS_RESERVED`.
+_WINDOWS_RESERVED = frozenset(
+    {"con", "prn", "aux", "nul"} | {f"com{i}" for i in range(1, 10)} | {f"lpt{i}" for i in range(1, 10)}
+)
+
+_PERCENT_RE = re.compile(r"%(?![0-9A-Fa-f]{2})")
+
+
+def _full(pattern: str, value: object) -> bool:
+    return isinstance(value, str) and re.fullmatch(pattern, value) is not None
+
+
+def is_test_id(value: object) -> bool:
+    return _full(TEST_ID_PATTERN, value)
+
+
+def is_tour_id(value: object) -> bool:
+    """A tour id names files (``<id>.<locale>.json``), so Windows device names are out."""
+    return _full(TOUR_ID_PATTERN, value) and str(value).casefold() not in _WINDOWS_RESERVED
+
+
+def is_layout_name(value: object) -> bool:
+    return _full(LAYOUT_NAME_PATTERN, value)
+
+
+def is_route(value: object) -> bool:
+    """A same-origin, base-relative route pattern the player will accept."""
+    if not isinstance(value, str) or len(value) > MAX_ROUTE_CHARS or not _full(ROUTE_PATTERN, value):
+        return False
+    if _PERCENT_RE.search(value):
+        return False
+    return not any(is_dot_segment(seg) for seg in value.split("/")[1:])
+
+
+def is_dot_segment(segment: str) -> bool:
+    """``.``/``..``, also spelled ``%2e`` — URL parsers resolve both, escaping the app's base path."""
+    return segment.lower().replace("%2e", ".") in (".", "..")
+
+
+def is_media_query(value: object) -> bool:
+    return _full(MEDIA_QUERY_PATTERN, value)
+
+
+def tour_file_name(tour_id: str, locale: str) -> str:
+    """``<tour-id>.<locale>.json`` — the only file names a manifest may list."""
+    return f"{tour_id}.{locale}.json"

steppy/tours/__init__.py

@@ -0,0 +1,22 @@
+"""In-app tours compiler: scenarios → tour files + replay plans.
+
+Lazily imported only (guard: ``tests/test_no_tours_import_on_default_path.py``):
+``steppy generate`` / ``validate`` / ``build`` reach it behind
+``tours.enabled``, and ``steppy tours`` through its leaf CLI module.
+
+Module map — each step of the pipeline is a module:
+
+* ``settings``   resolved, immutable view of ``config.yaml``'s ``tours:`` block
+* ``actions``    the per-action table (``ACTION_TOUR_KIND``) and step candidates
+* ``routes``     entry-route normalisation, matching and parameter binding
+* ``inference``  one scenario → kept tour steps + per-step replay dispositions
+* ``text``       per-locale titles/texts, leak and link checks
+* ``ids``        tour and step ids (never positional)
+* ``compiler``   all opted-in scenarios → ``TourCompileResult``
+* ``emit``       payloads, canonical bytes, SRI, write plans, prune
+* ``pipeline``   the entry point ``generate`` and ``tours`` share
+* ``publish``    the ``steppy build`` side (guide target)
+* ``replay``     ``ReplayPlan`` → what the test template renders
+
+Nothing here imports ``steppy.guide`` (markdown-it) or Playwright.
+"""