steppy-dev 0.3.0__py3-none-any.whl

steppy/tours/text.py

@@ -0,0 +1,237 @@
+"""Per-locale tour text.
+
+The ladder for a step and locale L is ``tour-text[L]`` → ``guide-text[L]``
+(each: exact tag, then base language) → nothing. "Nothing" is legitimate: the
+player then shows a generic, localised instruction chosen by the advance kind
+("Click the highlighted element"). Languages are never mixed — a French tour
+never borrows the English step text — and the compiler warns per step.
+
+A locale is emitted for a tour when at least one kept step has authored text in
+it; the default locale is always emitted.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+from urllib.parse import urljoin
+
+from ..locales import base_language
+from ..models import GuideText, GuideTextContent, Scenario, Step
+from ..tour_spec import MAX_TEXT_CHARS, MAX_TITLE_CHARS
+from .diagnostics import DiagSink
+from .model import TourStepPlan
+from .settings import ToursSettings, origin_of
+
+_LINK = re.compile(r"\[([^\]]+)\]\(([^)\s]+)\)")
+
+
+def content_for(step: Step, locale: str) -> Optional[GuideTextContent]:
+    for text in (step.tour_text, step.guide_text):
+        if text is not None:
+            found = text.get(locale)
+            if found is not None:
+                return found
+    return None
+
+
+def title_text(content: Optional[GuideTextContent]) -> tuple[Optional[str], Optional[str]]:
+    """``(title, body)`` for a popover.
+
+    A legacy string ``guide-text: "Do this. Then that."`` stores the first
+    sentence as the title *and* the whole string as the text; showing both would
+    repeat the sentence, so the derived title is dropped. A block with a title
+    and no text shows the title as the body.
+    """
+    if content is None:
+        return None, None
+    title = (content.title or "").strip() or None
+    text = (content.text or "").strip() or None
+    if text is None:
+        return None, title
+    if title is not None:
+        legacy = text.split(".")[0].strip() if "." in text else text.strip()
+        if title == legacy:
+            title = None
+    return title, text
+
+
+def tour_title(scenario: Scenario, locale: str, default_locale: str) -> tuple[str, bool]:
+    """``(title, fell_back)`` — ``tour.title`` per locale, else the scenario title.
+
+    A per-locale map is read exact tag → base language → the default locale (and
+    its base) — the rung ``pick_locale`` gives guide titles — and only then falls
+    back to the scenario title. ``fell_back`` is True whenever the title is not
+    in ``locale``'s own language; without a ``tour.title`` it is False (the caller
+    reports that case once for the whole project).
+    """
+    wanted = scenario.tour.title if scenario.tour else None
+    if isinstance(wanted, str):
+        return wanted.strip(), False
+    if isinstance(wanted, dict):
+        own = (locale, base_language(locale))
+        for key in (*own, default_locale, base_language(default_locale)):
+            if key in wanted:
+                return wanted[key].strip(), key not in own
+        return scenario.title.strip(), True
+    return scenario.title.strip(), False
+
+
+def emitted_locales(scenario: Scenario, steps: list[TourStepPlan], settings: ToursSettings) -> tuple[str, ...]:
+    out = []
+    for locale in settings.locales:
+        if locale == settings.default_locale or any(
+            content_for(scenario.steps[p.step_index], locale) is not None for p in steps
+        ):
+            out.append(locale)
+    return tuple(out)
+
+
+def guide_url(scenario: Scenario, settings: ToursSettings, locale: str) -> Optional[str]:
+    if not settings.guide_base_url:
+        return None
+    slug = scenario.tour.guide_slug if scenario.tour else None
+    if slug is None and scenario.guide.enabled:
+        slug = scenario.slug
+    if not slug:
+        return None
+    return urljoin(settings.guide_base_url, f"{slug}/{locale}.html")
+
+
+def leak_values(scenario: Scenario, steps: list[TourStepPlan]) -> dict[int, list[str]]:
+    """Literal fixture values per kept scenario step (``${…}``/``{{…}}`` are not knowable)."""
+    out: dict[int, list[str]] = {}
+    for idx in sorted({p.step_index for p in steps}):
+        step = scenario.steps[idx]
+        values: list[Optional[str]] = []
+        if step.action in ("fill", "select"):
+            values.append(step.value)
+        if step.action == "fill-form" and step.fields:
+            values.extend(step.fields.values())
+        if step.action == "select-option":
+            values.append(step.search)
+            if step.option and step.option.startswith("text:"):
+                values.append(step.option[5:].strip().strip('"').strip("'"))
+            values.extend(step.multiple or [])
+        clean = [
+            str(v).strip()
+            for v in values
+            if v is not None and "${" not in str(v) and "{{" not in str(v) and len(str(v).strip()) >= 2
+        ]
+        if clean:
+            out[idx] = clean
+    return out
+
+
+def check_texts(
+    scenario: Scenario,
+    steps: list[TourStepPlan],
+    texts: dict[str, list[tuple[Optional[str], Optional[str]]]],
+    settings: ToursSettings,
+    sink: DiagSink,
+) -> None:
+    """Leaks, links, limits, untargeted ``tour-text`` locales and generic-text warnings."""
+    values = leak_values(scenario, steps)
+    reported: set[tuple[int, str]] = set()
+    for n, plan in enumerate(steps):
+        step = scenario.steps[plan.step_index]
+        for locale, rows in texts.items():
+            title, body = rows[n]
+            for label, value, limit in (("title", title, MAX_TITLE_CHARS), ("text", body, MAX_TEXT_CHARS)):
+                if value is not None and len(value) > limit:
+                    sink.add(
+                        "limit-exceeded", f"the {locale} step {label} is longer than {limit} characters", step=step
+                    )
+            joined = " ".join(v for v in (title, body) if v)
+            for value in values.get(plan.step_index, []):
+                if (plan.step_index, value) in reported:
+                    continue
+                if re.search(r"(?<!\w)" + re.escape(value) + r"(?!\w)", joined, re.IGNORECASE):
+                    reported.add((plan.step_index, value))
+                    sink.add(
+                        "fixture-leak",
+                        f"the {locale} text mentions the test value {value!r}; the tour would ask real users to type test data",
+                        step=step,
+                        hint="give the step a `tour-text` without it",
+                    )
+            for _label, url in _LINK.findall(joined):
+                if not _link_allowed(url, settings):
+                    sink.add(
+                        "text-link-dropped",
+                        f"the link {url!r} in the {locale} text will render as plain text "
+                        "(only app routes and the guide site are linked)",
+                        step=step,
+                    )
+    for idx in sorted({p.step_index for p in steps}):
+        step = scenario.steps[idx]
+        missing = [loc for loc in texts if content_for(step, loc) is None]
+        if missing:
+            sink.add(
+                "generic-text",
+                f"no text for {', '.join(missing)}; the player will show a generic instruction",
+                step=step,
+                hint="add `guide-text` or `tour-text`",
+            )
+        for label, text in (("tour-text", step.tour_text), ("guide-text", step.guide_text)):
+            for key in _text_keys(text):
+                if key in settings.locales or any(base_language(loc) == key for loc in settings.locales):
+                    continue
+                # Keys are read exactly (`GuideText.get`), while the overlay ignores case and
+                # -/_: a near miss silently becomes the generic hint in the compiled tour.
+                folded = key.casefold().replace("_", "-")
+                near = next(
+                    (c for loc in settings.locales for c in (loc, base_language(loc)) if c.casefold() == folded),
+                    None,
+                )
+                if near is not None:
+                    sink.add(
+                        "tour-text-locale-untargeted",
+                        f"{label} has a {key!r} entry; locale keys are read exactly — did you mean {near!r}?",
+                        step=step,
+                    )
+                elif label == "tour-text":
+                    sink.add(
+                        "tour-text-locale-untargeted",
+                        f"tour-text has a {key!r} entry, but tours do not target that locale",
+                        step=step,
+                    )
+
+
+def _text_keys(text: Optional[GuideText]) -> list[str]:
+    """The locale keys a ``guide-text``/``tour-text`` block sets, in authored order."""
+    if text is None:
+        return []
+    keys = [n for n in ("fr", "en", "nl", "de") if getattr(text, n) is not None]
+    return keys + list((text.model_extra or {}).keys())
+
+
+def _resolved_path(path: str) -> str:
+    """``path`` after dot-segment removal, as a browser resolves it (``%2e`` is a dot)."""
+    out: list[str] = []
+    segments = path.split("/")[1:]
+    for n, seg in enumerate(segments):
+        if seg.lower().replace("%2e", ".") in (".", ".."):
+            if seg.lower().replace("%2e", ".") == ".." and out:
+                out.pop()
+            if n == len(segments) - 1:
+                out.append("")
+        else:
+            out.append(seg)
+    return "/" + "/".join(out)
+
+
+def _link_allowed(url: str, settings: ToursSettings) -> bool:
+    if url.startswith("/") and not url.startswith("//") and not url.startswith("/\\"):
+        # The overlay checks the *resolved* href: `/.//host` collapses into `//host`.
+        if re.search(r"[\\\s\x00-\x1f\x7f]", url):
+            return False
+        return not _resolved_path(re.split(r"[?#]", url, maxsplit=1)[0]).startswith("//")
+    return settings.guide_origin is not None and origin_of(url) == settings.guide_origin
+
+
+def resolve_texts(
+    scenario: Scenario, steps: list[TourStepPlan], locales: tuple[str, ...]
+) -> dict[str, list[tuple[Optional[str], Optional[str]]]]:
+    return {
+        locale: [title_text(content_for(scenario.steps[p.step_index], locale)) for p in steps] for locale in locales
+    }

steppy/tours_cli.py

@@ -0,0 +1,219 @@
+"""``steppy tours`` — compile in-app tours — and the tour hooks of ``generate``/``validate``.
+
+A leaf CLI module registered via ``register_tours(app)``. Everything under
+:mod:`steppy.tours` is imported *inside* function bodies, so
+``import steppy.cli`` stays free of it
+(``tests/test_no_tours_import_on_default_path.py``), and a project without a
+``tours:`` block never loads it at all.
+
+``steppy tours`` writes the tour files without touching the tests: it is the
+command an app's own build pipeline runs to bundle its tours. ``steppy
+generate`` does the same and also appends the CI replays.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+import typer
+from rich.markup import escape
+
+from ._cli_common import _cli_errors, _error, _load_config_or_exit, console
+from .models import SteppyConfig, Scenario
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .tours.diagnostics import Diagnostic
+    from .tours.pipeline import TourPipeline
+
+_STYLE = {"error": "[red]ERROR[/red]", "warning": "[yellow]WARNING[/yellow]", "info": "[dim]INFO[/dim]"}
+
+
+def tours_enabled(config: SteppyConfig) -> bool:
+    return config.tours is not None and config.tours.enabled
+
+
+def print_tour_diagnostics(diagnostics: "list[Diagnostic]", *, show_info: bool = False) -> None:
+    for diag in diagnostics:
+        if diag.severity == "info" and not show_info:
+            continue
+        console.print(f"{_STYLE[diag.severity]} {escape(diag.render())}")
+
+
+def print_file_statuses(statuses: dict[str, str], *, dry_run: bool = False) -> None:
+    labels = {
+        "generated": "[green]+ GENERATED[/green]",
+        "updated": "[yellow]~ UPDATED[/yellow]  ",
+        "unchanged": "[dim]= UNCHANGED[/dim]",
+        "removed": "[red]- REMOVED[/red]  ",
+        "missing": "[red]! MISSING[/red]  ",
+    }
+    cwd = Path.cwd()
+    for path, status in statuses.items():
+        shown = Path(path)
+        if cwd in shown.parents:
+            shown = shown.relative_to(cwd)
+        console.print(f"  {labels.get(status, status)} {escape(str(shown))}")
+
+
+def warn_opted_in_but_disabled(config: SteppyConfig, scenarios: list[Scenario]) -> None:
+    """One hint when scenarios ask for tours that the config does not produce."""
+    if tours_enabled(config):
+        return
+    wanting = [s.slug for s in scenarios if s.tour is not None and s.tour.enabled]
+    if wanting:
+        console.print(
+            f"[yellow]WARNING[/yellow] {len(wanting)} scenario(s) set `tour:` but in-app tours are off "
+            "(set tours.enabled: true in config.yaml): " + escape(", ".join(sorted(wanting)[:5]))
+        )
+
+
+def prepare_tours_or_exit(
+    config: SteppyConfig,
+    *,
+    scenarios_dir: Path,
+    selected: Optional[list[Scenario]] = None,
+    all_scenarios: Optional[list[Scenario]] = None,
+    build_id_override: Optional[str] = None,
+    mode: str = "generate",
+    show_info: bool = False,
+) -> "TourPipeline":
+    """Compile tours, print diagnostics, and exit 1 on any error (nothing written yet)."""
+    from .tours.pipeline import prepare_tours
+
+    pipeline = prepare_tours(
+        config,
+        project_root=Path.cwd(),
+        scenarios_dir=scenarios_dir,
+        selected=selected,
+        all_scenarios=all_scenarios,
+        build_id_override=build_id_override,
+        mode=mode,  # type: ignore[arg-type]
+    )
+    print_tour_diagnostics(pipeline.diagnostics, show_info=show_info)
+    if pipeline.has_errors:
+        _error("In-app tours have errors; nothing was written (fix them, or set tours.enabled: false)")
+        raise typer.Exit(1)
+    return pipeline
+
+
+def run_tour_checks(config: SteppyConfig, scenarios: list[Scenario], *, scenarios_dir: Path) -> bool:
+    """``steppy validate``'s tour pass; returns True when there are errors."""
+    if not tours_enabled(config):
+        warn_opted_in_but_disabled(config, scenarios)
+        return False
+    from .tours.pipeline import prepare_tours
+
+    pipeline = prepare_tours(
+        config, project_root=Path.cwd(), scenarios_dir=scenarios_dir, all_scenarios=scenarios, mode="validate"
+    )
+    print_tour_diagnostics(pipeline.diagnostics)
+    if not pipeline.has_errors and pipeline.result is not None:
+        count = len(pipeline.result.tours)
+        console.print(f"[green]OK[/green] {count} in-app tour(s) compile")
+    return pipeline.has_errors
+
+
+def register_tours(app: typer.Typer) -> None:
+    app.command(name="tours")(tours_command)
+
+
+def tours_command(
+    scenarios_dir: Path = typer.Option(
+        Path("scenarios"), "--scenarios-dir", "-d", help="Directory containing scenario files"
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be written without writing anything"),
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="CI gate: exit 1 if an app-assets copy is missing or its content is stale (writes nothing; "
+        "compares against the build id each copy records)",
+    ),
+    build_id: Optional[str] = typer.Option(
+        None, "--build-id", help="Build id to stamp, overriding tours.build_id (same grammar)"
+    ),
+    explain: bool = typer.Option(False, "--explain", help="Also print why each step was left out of its tour"),
+) -> None:
+    """Compile in-app tours from every `tour:`-enabled scenario.
+
+    Writes <output.tours_dir>/<build-id>/ and a flat copy into every app-assets
+    target of the `tours:` block in config.yaml. Tests are not touched; use
+    `steppy generate` for the CI replays.
+
+    --check compares only the app-assets copies (the files an app commits), for
+    the build id each one records: the canonical tree is a gitignored build
+    output, and committed copies always carry an older id under git-sha.
+    """
+    with _cli_errors():
+        config = _load_config_or_exit()
+        if not tours_enabled(config):
+            _error("In-app tours are disabled: add a `tours:` block with `enabled: true` to config.yaml")
+            raise typer.Exit(1)
+        if not scenarios_dir.is_dir():
+            _error(f"Scenarios directory not found: {scenarios_dir}")
+            raise typer.Exit(1)
+        pipeline = prepare_tours_or_exit(
+            config,
+            scenarios_dir=scenarios_dir,
+            build_id_override=build_id,
+            mode="check" if check else "tours",
+            show_info=explain,
+        )
+        if check:
+            _report_check(pipeline)
+            return
+        statuses = pipeline.emit(dry_run=dry_run)
+        console.print(f"\n[bold]In-app tours[/bold] (build {escape(str(pipeline.build_id))})")
+        print_file_statuses(statuses)
+        counts = {k: sum(1 for s in statuses.values() if s == k) for k in ("generated", "updated", "removed")}
+        verb = "would be " if dry_run else ""
+        console.print(
+            f"\n[green]Summary:[/green] {len(pipeline.result.tours) if pipeline.result else 0} tour(s); "
+            f"{counts['generated']} {verb}generated, {counts['updated']} {verb}updated, "
+            f"{counts['removed']} {verb}removed"
+        )
+
+
+def _report_check(pipeline: "TourPipeline") -> None:
+    """``--check``: print what differs in the app-assets copies; exit 1 when anything does."""
+    if not pipeline.settings.app_assets_dirs:
+        console.print(
+            "[green]OK[/green] Tours compile; no app-assets target is configured, so there are no committed "
+            "tour files to compare"
+        )
+        return
+    statuses = pipeline.statuses()
+    targets = len(pipeline.settings.app_assets_dirs)
+    console.print(f"\n[bold]In-app tours[/bold] (checking {targets} app-assets target(s))")
+    print_file_statuses(statuses)
+    for directory, recorded in pipeline.checked.items():
+        if recorded is None or recorded == pipeline.build_id:
+            continue
+        here = (
+            f"the build id here is {pipeline.build_id!r}"
+            if pipeline.build_id
+            else f"the build id cannot be resolved here ({pipeline.build_id_error})"
+        )
+        console.print(
+            f"[dim]NOTE[/dim] {escape(str(directory))} holds the tours of build {recorded!r} and {escape(here)}; "
+            "its content was compared for its own build"
+        )
+    stale = sum(1 for s in statuses.values() if s != "unchanged")
+    for plan in pipeline.plans:
+        eol_only = [
+            name
+            for name, data in plan.writes.items()
+            if (plan.directory / name).is_file()
+            and (on_disk := (plan.directory / name).read_bytes()) != data
+            and on_disk.replace(b"\r\n", b"\n") == data
+        ]
+        if eol_only:
+            console.print(
+                f"[yellow]HINT[/yellow] {len(eol_only)} file(s) in {escape(str(plan.directory))} differ only in line "
+                "endings: git converted them on checkout, and regenerating cannot fix that. Mark the folder binary "
+                "in the app repository's .gitattributes (`<folder>/*.json -text`)."
+            )
+    if stale:
+        _error(f"{stale} tour file(s) are missing or stale; run `steppy tours` and commit the result")
+        raise typer.Exit(1)
+    console.print("\n[green]OK[/green] Tour files are up to date")