pytest-given 0.1.0__py3-none-any.whl

pytest_given/capture/source.py

@@ -0,0 +1,208 @@
+"""Caller-frame source-location capture for non-pytest-item objects.
+
+`Story` and `GlossaryTerm` are constructed at user-code import time, not
+inside a pytest hook, so their source-location must be reconstructed from
+the call stack. The plugin sets rootdir during `pytest_load_initial_conftests`
+(before root conftest is imported); capture sites then call
+`capture_caller_source(skip=N)` from their user-facing wrappers. Returns
+None if rootdir is unset or the caller's file lies outside rootdir — the
+renderer treats that as "no link", same as a scenario whose `item.location`
+is absent.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import types
+from pathlib import Path
+
+from ..model import SourceLocation
+
+_WINDOWS_PATH_RE = re.compile(r'^([A-Za-z]):[\\/]')
+_MNT_PATH_RE = re.compile(r'^[\\/]mnt[\\/]([A-Za-z])(?=[\\/]|$)')
+
+# Detecting WSL and native Windows specifically (rather than "not the other")
+# keeps each rewrite below from firing on plain Linux or macOS, where /mnt/<drive>
+# is a real directory and a Windows-style co_filename should never occur.
+_IS_WSL = (
+    sys.platform == 'linux'
+    and Path('/proc/version').exists()
+    and 'microsoft' in Path('/proc/version').read_text().lower()
+)
+_IS_WINDOWS = sys.platform == 'win32'
+
+
+def _co_filename_to_path(filename: str) -> Path:
+    """Normalise a path string to the running platform's native convention.
+
+    The same file can reach us in either convention regardless of platform: a
+    frame's `co_filename` (or a stored rootdir) may be a Windows path
+    (``C:\\...``) or a WSL-mount POSIX path (``/mnt/<drive>/...``). A native
+    Windows interpreter that loads an assertion-rewritten ``.pyc`` previously
+    compiled under WSL, for instance, carries a ``/mnt/c/...`` co_filename for a
+    file the rest of the process knows as ``C:\\...``. Comparing the two
+    conventions with `relative_to` fails (mismatched drive anchors), so we fold
+    whichever foreign form we see into the native one:
+
+    - Under WSL (Linux kernel, Windows filesystem): ``C:\\...`` -> ``/mnt/c/...``
+    - Under native Windows: ``/mnt/<drive>/...`` -> ``<drive>:\\...``
+
+    On plain Linux/macOS nothing is rewritten — there ``/mnt/<drive>`` is a real
+    directory and must be left alone.
+    """
+    if _IS_WSL:
+        match = _WINDOWS_PATH_RE.match(filename)
+        if match:
+            rest = filename[2:].replace('\\', '/')
+            return Path(f'/mnt/{match.group(1).lower()}{rest}')
+    elif _IS_WINDOWS:
+        match = _MNT_PATH_RE.match(filename)
+        if match:
+            rest = filename[match.end() :] or '/'
+            return Path(f'{match.group(1).upper()}:{rest}')
+    return Path(filename)
+
+
+_rootdir: Path | None = None
+
+# path string -> rootdir-relative result, valid only for the current _rootdir.
+# `Path.resolve` lstats every path component, and with the lint enabled it runs
+# once per captured step — memoizing per file keeps that O(distinct files)
+# instead of O(steps), which matters on slow mounts (WSL 9p: ~2ms per resolve).
+_relpath_cache: dict[str, str | None] = {}
+
+
+def set_rootdir(path: Path) -> None:
+    """Called by the plugin in `pytest_load_initial_conftests`.
+
+    Folded into the native convention first (see `_co_filename_to_path`) so the
+    rootdir and the captured `co_filename`s always share a drive anchor — e.g. a
+    ``/mnt/c/...`` rootdir on native Windows resolves to ``C:\\mnt\\c\\...``
+    rather than the real ``C:\\...`` and would never match.
+    """
+    global _rootdir
+    _rootdir = _co_filename_to_path(str(path)).resolve()
+    _relpath_cache.clear()
+
+
+def current_rootdir() -> Path | None:
+    """The rootdir as last set (already resolved). The plugin saves this before
+    a nested in-process run re-points it via `set_rootdir`, and hands it back
+    to `restore_rootdir` when that run unconfigures."""
+    return _rootdir
+
+
+def restore_rootdir(previous: Path | None) -> None:
+    """Reinstate a rootdir captured with `current_rootdir`. Unlike
+    `set_rootdir`, the value is used as-is — it was already normalised and
+    resolved when first set. Clears the relpath cache, whose entries are only
+    valid for the rootdir they were computed against."""
+    global _rootdir
+    _rootdir = previous
+    _relpath_cache.clear()
+
+
+def _reset_rootdir() -> None:
+    """Test-only — reset module state between cases."""
+    global _rootdir
+    _rootdir = None
+    _relpath_cache.clear()
+
+
+def _relativize(abs_path: Path) -> str | None:
+    """rootdir-relative POSIX string for an absolute path. Returns None if
+    rootdir is unset or the path lies outside it. Callers that start from a
+    `co_filename` must normalise via `_co_filename_to_path` first.
+    """
+    if _rootdir is None:
+        return None
+    key = str(abs_path)
+    if key in _relpath_cache:
+        return _relpath_cache[key]
+    try:
+        rel: str | None = abs_path.resolve().relative_to(_rootdir).as_posix()
+    except ValueError:
+        rel = None
+    _relpath_cache[key] = rel
+    return rel
+
+
+def _optional_source(abs_path: Path, line: int) -> SourceLocation | None:
+    """SourceLocation for an absolute path, or None when it can't be made
+    rootdir-relative (rootdir unset or path outside it) — i.e. "no link". The
+    counterpart to `to_relpath`, which instead degrades to the path as given.
+    """
+    rel = _relativize(abs_path)
+    return None if rel is None else SourceLocation(relpath=rel, line=line)
+
+
+def capture_caller_source(skip: int = 1) -> SourceLocation | None:
+    """Return a SourceLocation for the frame `skip` levels up the call stack.
+
+    `skip=1` (default) returns the immediate caller of `capture_caller_source`.
+    Use `skip=2` when called from a one-level-deep user-facing wrapper (e.g.
+    `g.actor("Guest")` -> wrapper -> this helper) so frame 2 is the user's
+    code.
+
+    Returns None if rootdir is unset, or if the caller's file resolves to a
+    path outside rootdir.
+    """
+    frame = sys._getframe(skip)
+    abs_path = _co_filename_to_path(frame.f_code.co_filename)
+    return _optional_source(abs_path, frame.f_lineno)
+
+
+def to_relpath(raw: str) -> str:
+    """Normalise a path string and make it rootdir-relative when possible.
+
+    Folds the path into the native convention (see `_co_filename_to_path`) and,
+    if it is then an absolute path inside rootdir, returns it relative to rootdir;
+    otherwise returns it unchanged as posix. Used for both scenario
+    `item.location` paths and traceback frame paths so neither leaks an absolute,
+    machine-specific path — the same file can surface absolute (and in the wrong
+    convention) when a `.pyc` compiled by the other interpreter is reused across
+    a shared WSL+Windows checkout.
+    """
+    path = _co_filename_to_path(raw)
+    if path.is_absolute():
+        rel = _relativize(path)
+        if rel is not None:
+            return rel
+    return path.as_posix()
+
+
+def item_source(relpath_raw: str, line: int) -> SourceLocation:
+    """Build a SourceLocation from a pytest `item.location` path + 1-based line.
+
+    `item.location[0]` is normally already rootdir-relative, but under WSL pytest
+    cannot relativize a Windows-style `co_filename` (e.g. ``C:\\Users\\...``)
+    against the POSIX ``/mnt/<drive>`` rootdir and falls back to the absolute
+    Windows path. `to_relpath` rewrites it to the native convention and
+    re-relativizes against rootdir. Unlike `capture_caller_source`, this always
+    returns a location: an absolute path outside rootdir (or unset rootdir)
+    degrades to the path as given rather than to "no link", matching the prior
+    behaviour where every scenario carried a source.
+    """
+    return SourceLocation(relpath=to_relpath(relpath_raw), line=line)
+
+
+def code_source(code: types.CodeType) -> SourceLocation | None:
+    """SourceLocation for a code object's definition site (used to anchor
+    decorated step-helper functions for the narration lint).
+
+    `co_firstlineno` points at the function's first decorator line when it has
+    decorators; the lint's AST index accounts for that. Returns None if rootdir
+    is unset or the file lies outside it.
+    """
+    abs_path = _co_filename_to_path(code.co_filename)
+    return _optional_source(abs_path, code.co_firstlineno)
+
+
+def file_source(path: Path, line: int) -> SourceLocation | None:
+    """SourceLocation for a known file path + line (e.g. a glossary table row).
+
+    Mirrors `capture_caller_source` but for a path we already hold rather than
+    a stack frame. Returns None if rootdir is unset or the file is outside it.
+    """
+    return _optional_source(path, line)

pytest_given/capture/story.py

@@ -0,0 +1,303 @@
+"""Story / Activity / Path constructors."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable, Sequence
+
+from ..model import (
+    Activity,
+    ActivityId,
+    ActivityPart,
+    ActivityPath,
+    ActivityTermRef,
+    ActivityWord,
+    Glossary,
+    PytestGivenError,
+    Story,
+    StoryId,
+    id_derive,
+)
+from .glossary import (
+    Actor,
+    ActorInstance,
+    DeferredTermHandle,
+    DeferredTermInstance,
+    InflectedVerb,
+    Verb,
+    WorkObject,
+    WorkObjectInstance,
+)
+from .source import capture_caller_source
+
+# Capture the built-in id() before it can be shadowed by local parameters.
+_obj_id = id
+
+type _PathArg = (
+    Actor
+    | WorkObject
+    | Verb
+    | ActorInstance
+    | WorkObjectInstance
+    | InflectedVerb
+    | DeferredTermHandle
+    | DeferredTermInstance
+    | str
+)
+
+# Even positions are graph nodes (entities); odd positions are edges (a verb
+# arrow or a bare-string connective). A DeferredTermHandle/Instance has no eager
+# kind, so it is structurally valid at either kind of position and resolved by
+# kind inference + _slot_for later.
+_ACTOR_TYPES = (Actor, ActorInstance, DeferredTermHandle, DeferredTermInstance)
+_VERB_TYPES = (Verb, InflectedVerb, DeferredTermHandle, DeferredTermInstance)
+_NODE_TYPES = (
+    Actor,
+    ActorInstance,
+    WorkObject,
+    WorkObjectInstance,
+    DeferredTermHandle,
+    DeferredTermInstance,
+)
+
+
+def path(*parts: _PathArg) -> ActivityPath:
+    """Build an ActivityPath as a node/edge alternation, so it maps directly
+    onto a Domain Storytelling graph. Even positions (0, 2, ...) are entity
+    nodes (actor / work object); odd positions (1, 3, ...) are edges — a verb
+    handle or a bare-string connective. Position 0 is an actor, position 1 a
+    verb — but any position also accepts a bare string (an ActivityWord that
+    carries no role). The path has odd length >= 3 and ends on a node."""
+    if len(parts) < 3 or len(parts) % 2 == 0:
+        raise PytestGivenError(
+            f'activity path must alternate node / edge / node … with an odd '
+            f'length >= 3 (it must start and end on an entity node); got '
+            f'{len(parts)} part(s): {parts!r}. A trailing arrow with no target '
+            f'is not allowed — split multi-arrow activities into separate '
+            f'path(...) calls.'
+        )
+    for position, part in enumerate(parts):
+        if isinstance(part, str):
+            continue  # a bare word carries no role; valid at any position
+        if position == 0:
+            _check_position(part, 0, 'actor', _ACTOR_TYPES, parts)
+        elif position % 2 == 1:
+            _check_position(part, position, 'verb', _VERB_TYPES, parts)
+        else:
+            _check_position(part, position, 'noun', _NODE_TYPES, parts)
+    schema_parts = tuple(_to_part(part) for part in parts)
+    # Stash the live Glossary objects the path references, keyed by object id —
+    # read by activity() and _check_single_glossary to enforce the v1 "one
+    # glossary per story" invariant at construction time, and by story() so the
+    # owning Glossary travels on the Story tree itself. plugin._resolve_glossary
+    # reads that stash to pick the report's glossary deterministically, without
+    # consulting any session-global. Keying by id() dedups by identity (Glossary
+    # is unhashable) while keeping the object. Not serialized.
+    glossaries: dict[int, Glossary] = {
+        _obj_id(owner): owner
+        for owner in (_glossary_of(part) for part in parts)
+        if owner is not None
+    }
+    path_obj = ActivityPath(parts=schema_parts)
+    object.__setattr__(path_obj, '_glossaries', glossaries)
+    return path_obj
+
+
+def _glossary_of(value: object) -> Glossary | None:
+    match value:
+        case Actor() | WorkObject() | Verb():
+            return value.glossary
+        case ActorInstance(actor=h):
+            return h.glossary
+        case WorkObjectInstance(work_object=h):
+            return h.glossary
+        case InflectedVerb(verb=h):
+            return h.glossary
+        case DeferredTermHandle():
+            return value.glossary
+        case DeferredTermInstance(handle=handle):
+            return handle.glossary
+    return None
+
+
+def activity(
+    *parts_or_paths: _PathArg | ActivityPath,
+    id: int | None = None,
+) -> Activity:
+    """Build an Activity from either positional parts (single path) or
+    positional ActivityPath instances (multi-path). Mixing raises.
+
+    `id=` overrides the default sequence number (0). `story(...)` reassigns
+    sequence numbers when activities are passed without explicit ids.
+    """
+    has_paths = any(isinstance(p, ActivityPath) for p in parts_or_paths)
+    has_parts = any(not isinstance(p, ActivityPath) for p in parts_or_paths)
+    if has_paths and has_parts:
+        raise PytestGivenError(
+            'activity(...) cannot mix ActivityPath instances with bare parts; '
+            'either pass parts (for a single path) or paths (for multi-path), '
+            'not both.'
+        )
+    if has_paths:
+        paths = tuple(p for p in parts_or_paths if isinstance(p, ActivityPath))
+    else:
+        paths = (path(*parts_or_paths),)  # type: ignore[arg-type]
+    glossaries = _merge_glossaries(getattr(p, '_glossaries', {}) for p in paths)
+    if id == 0:
+        raise PytestGivenError(
+            'activity(id=0) is reserved as the unset sentinel; '
+            'use id=1.. or omit to take the auto-assigned sequence number.'
+        )
+    a = Activity(id=ActivityId(id if id is not None else 0), paths=paths)
+    object.__setattr__(a, '_glossaries', glossaries)
+    return a
+
+
+def _merge_glossaries(
+    stashes: Iterable[dict[int, Glossary]],
+) -> dict[int, Glossary]:
+    """Union the id→Glossary stashes of several paths/activities, deduping by
+    object identity."""
+    merged: dict[int, Glossary] = {}
+    for stash in stashes:
+        merged.update(stash)
+    return merged
+
+
+_STORY_REGISTRY: dict[StoryId, str] = {}
+
+
+def clear_story_registry() -> None:
+    _STORY_REGISTRY.clear()
+
+
+def snapshot_story_registry() -> dict[StoryId, str]:
+    """A copy of the registry. The plugin takes one before clearing at
+    sessionstart, so a nested in-process run can hand the outer session's
+    registrations back via `restore_story_registry` when it unconfigures."""
+    return dict(_STORY_REGISTRY)
+
+
+def restore_story_registry(snapshot: dict[StoryId, str]) -> None:
+    """Reinstate a snapshot taken with `snapshot_story_registry`."""
+    _STORY_REGISTRY.clear()
+    _STORY_REGISTRY.update(snapshot)
+
+
+def _register_story(sid: StoryId, title: str) -> None:
+    frame = sys._getframe(2)
+    site = f'{frame.f_code.co_filename}:{frame.f_lineno}'
+    if sid in _STORY_REGISTRY:
+        raise PytestGivenError(
+            f'story {title!r} (id {sid!r}) already declared at '
+            f'{_STORY_REGISTRY[sid]}; declaring it again at {site}.'
+        )
+    _STORY_REGISTRY[sid] = site
+
+
+def story(title: str, activities: Sequence[Activity] = ()) -> Story:
+    """Construct a Story. Reassigns auto-numbered ids, validates uniqueness,
+    and enforces v1's single-glossary invariant."""
+    sid = StoryId(id_derive(title))
+    _register_story(sid, title)
+    source = capture_caller_source(skip=2)
+    numbered = _assign_sequence_numbers(tuple(activities))
+    _check_unique_ids(numbered)
+    glossaries = _merge_glossaries(getattr(a, '_glossaries', {}) for a in numbered)
+    _check_single_glossary(title, glossaries)
+    result = Story(id=sid, title=title, activities=numbered, source=source)
+    # Carry the story's glossary on the tree so plugin._resolve_glossary can
+    # pick it deterministically from the collected stories themselves.
+    object.__setattr__(result, '_glossaries', glossaries)
+    return result
+
+
+def _assign_sequence_numbers(
+    activities: tuple[Activity, ...],
+) -> tuple[Activity, ...]:
+    """Activities passed with id=0 (the unset sentinel) get sequential ids
+    skipping any explicit ids already taken; activities with an explicit id
+    keep theirs."""
+    taken: set[ActivityId] = {a.id for a in activities if a.id != 0}
+    out: list[Activity] = []
+    next_seq = 1
+    for a in activities:
+        if a.id != 0:
+            out.append(a)
+            continue
+        while ActivityId(next_seq) in taken:
+            next_seq += 1
+        new = Activity(id=ActivityId(next_seq), paths=a.paths)
+        object.__setattr__(new, '_glossaries', getattr(a, '_glossaries', {}))
+        out.append(new)
+        next_seq += 1
+    return tuple(out)
+
+
+def _check_unique_ids(activities: tuple[Activity, ...]) -> None:
+    seen: set[ActivityId] = set()
+    for a in activities:
+        if a.id in seen:
+            raise PytestGivenError(
+                f'duplicate activity id {a.id} in story; activity ids must be unique.'
+            )
+        seen.add(a.id)
+
+
+def _check_single_glossary(title: str, glossaries: dict[int, Glossary]) -> None:
+    if len(glossaries) > 1:
+        raise PytestGivenError(
+            f'story {title!r} spans multiple glossaries ({len(glossaries)}); '
+            f'v1 supports at most one glossary per story.'
+        )
+
+
+def _check_position(
+    value: object,
+    pos: int,
+    role: str,
+    accepted: tuple[type, ...],
+    full_parts: tuple[object, ...],
+) -> None:
+    if isinstance(value, accepted):
+        return
+    raise PytestGivenError(
+        f'activity path position {pos} must be a glossary {role} handle or a '
+        f'bare string; got {type(value).__name__}: {value!r}. '
+        f'{_suggestion_for(role)} Full parts: {full_parts!r}'
+    )
+
+
+def _suggestion_for(role: str) -> str:
+    if role == 'actor':
+        return (
+            'Position 0 is the actor node — pass an actor handle '
+            '(g.actor("…") / g("…")) or a bare string, not a work object or verb.'
+        )
+    if role == 'verb':
+        return (
+            'An edge takes a verb handle (g.verb("…") / g("…")) or a bare '
+            'connective string, not an actor or work object.'
+        )
+    return (
+        'A node takes an actor or work-object handle (g.work_object("…") / '
+        'g("…")) or a bare string, not a verb.'
+    )
+
+
+def _to_part(value: _PathArg) -> ActivityPart:
+    match value:
+        case Actor() | WorkObject() | Verb():
+            return ActivityTermRef(term_id=value.id, display=value.canonical)
+        case ActorInstance(actor=actor, display=display):
+            return ActivityTermRef(term_id=actor.id, display=display)
+        case WorkObjectInstance(work_object=wo, display=display):
+            return ActivityTermRef(term_id=wo.id, display=display)
+        case InflectedVerb(verb=verb, display=display):
+            return ActivityTermRef(term_id=verb.id, display=display)
+        case DeferredTermHandle():
+            return ActivityTermRef(term_id=value.id, display=value.canonical)
+        case DeferredTermInstance(handle=handle, display=display):
+            return ActivityTermRef(term_id=handle.id, display=display)
+        case str():
+            return ActivityWord(text=value)

pytest_given/capture/template.py

@@ -0,0 +1,180 @@
+from collections.abc import Mapping
+from string import Formatter, templatelib
+from typing import Any
+
+from ..model import (
+    Narration,
+    NarrationLiteral,
+    NarrationPart,
+    NarrationPlaceholder,
+    NarrationTermRef,
+    NarrationValue,
+    PytestGivenError,
+)
+from .glossary import (
+    Actor,
+    ActorInstance,
+    DeferredTermHandle,
+    DeferredTermInstance,
+    InflectedVerb,
+    Verb,
+    WorkObject,
+    WorkObjectInstance,
+)
+
+_FORMATTER = Formatter()
+
+
+def narration_from(
+    value: str | Template | templatelib.Template | Narration,
+) -> Narration:
+    """Build a Narration from a plain string, a Template, a t-string, or an
+    already-rendered Narration (which passes through unchanged — used for eager
+    glossary-t-string scenario names)."""
+    if isinstance(value, Narration):
+        return value
+    if isinstance(value, templatelib.Template):
+        text, parts = parse_tstring(value)
+        return Narration(text=text, parts=parts)
+    if isinstance(value, Template):
+        return Narration(text=value.template, parts=list(value.parts))
+    return Narration(text=value)
+
+
+class Template:
+    """Deferred brace-style template. Same `{...}` syntax as f/t-strings.
+
+    Supports bare identifiers only — `{name}`, `{name:spec}`, `{name!conv}`.
+    Attribute access, indexing, and arbitrary expressions raise PytestGivenError
+    at construction time.
+    """
+
+    def __init__(self, template: str) -> None:
+        self.template = template
+        parts: list[NarrationPart] = []
+        for literal, name, spec, conversion in _FORMATTER.parse(template):
+            if literal:
+                parts.append(NarrationLiteral(value=literal))
+            if name is not None:
+                if not name.isidentifier():
+                    raise PytestGivenError(
+                        f'pytest_given.Template only supports bare identifiers '
+                        f'as placeholders; got {name!r}. For attribute access '
+                        f'or expressions, use a t-string in the test body '
+                        f'(where the value is in scope).'
+                    )
+                parts.append(
+                    NarrationPlaceholder(
+                        name=name,
+                        format_spec=spec or '',
+                        conversion=conversion,
+                    )
+                )
+        self.parts: list[NarrationPart] = parts
+
+    def substitute(self, mapping: Mapping[str, Any]) -> str:
+        out: list[str] = []
+        for part in self.parts:
+            match part:
+                case NarrationLiteral(value=value):
+                    out.append(value)
+                case NarrationPlaceholder(name=name, format_spec=spec, conversion=conv):
+                    if name not in mapping:
+                        raise KeyError(name)
+                    resolved = _FORMATTER.convert_field(mapping[name], conv)
+                    out.append(format(resolved, spec))
+        return ''.join(out)
+
+    def get_identifiers(self) -> list[str]:
+        return [p.name for p in self.parts if isinstance(p, NarrationPlaceholder)]
+
+
+def parse_tstring(
+    tstring: templatelib.Template,
+) -> tuple[str, list[NarrationPart]]:
+    """Convert a t-string Template into (rendered text, structured parts).
+
+    Iterates the t-string yielding str | Interpolation. Each interpolation
+    is inspected:
+    - Glossary handles (Actor, WorkObject, Verb, and their instances/inflections)
+      become NarrationTermRef carrying term_id, display, and the source expression.
+    - All other values become NarrationValue as before.
+    """
+    parts: list[NarrationPart] = []
+    rendered_chunks: list[str] = []
+    for chunk in tstring:
+        match chunk:
+            case str() as literal:
+                if literal:
+                    parts.append(NarrationLiteral(value=literal))
+                    rendered_chunks.append(literal)
+            case templatelib.Interpolation(
+                value=value,
+                expression=expression,
+                conversion=conversion,
+                format_spec=format_spec,
+            ):
+                term_ref = _try_term_ref(
+                    value, expression, format_spec=format_spec, conversion=conversion
+                )
+                if term_ref is not None:
+                    parts.append(term_ref)
+                    rendered_chunks.append(term_ref.display)
+                    continue
+                rendered = format(
+                    _FORMATTER.convert_field(value, conversion), format_spec
+                )
+                parts.append(
+                    NarrationValue(
+                        rendered=rendered,
+                        expression=expression,
+                        format_spec=format_spec,
+                        conversion=conversion,
+                    )
+                )
+                rendered_chunks.append(rendered)
+    return ''.join(rendered_chunks), parts
+
+
+def _try_term_ref(
+    value: object,
+    expression: str = '',
+    *,
+    format_spec: str = '',
+    conversion: str | None = None,
+) -> NarrationTermRef | None:
+    """Return a NarrationTermRef if `value` is a glossary handle, instance, or
+    inflection — else None (fall back to NarrationValue).
+
+    Glossary handles render as kind-coloured pills carrying the term's
+    canonical or instance display; format_spec and conversion have no
+    meaningful target on a pill, so a non-empty value is rejected at
+    parse time rather than silently dropped.
+    """
+    match value:
+        case Actor() | WorkObject() | Verb():
+            display = value.canonical
+            term_id = value.id
+        case ActorInstance(actor=h, display=display):
+            term_id = h.id
+        case WorkObjectInstance(work_object=h, display=display):
+            term_id = h.id
+        case InflectedVerb(verb=h, display=display):
+            term_id = h.id
+        case DeferredTermHandle():
+            display = value.canonical
+            term_id = value.id
+        case DeferredTermInstance(handle=handle, display=display):
+            term_id = handle.id
+        case _:
+            return None
+    if format_spec or conversion:
+        suffix = f':{format_spec}' if format_spec else ''
+        conv = f'!{conversion}' if conversion else ''
+        raise PytestGivenError(
+            f'glossary term interpolation {{{expression}{conv}{suffix}}} '
+            f'cannot carry a format spec or conversion — glossary handles '
+            f'render as kind pills with a fixed display ({display!r}). '
+            f'Drop the spec, or interpolate the underlying value separately.'
+        )
+    return NarrationTermRef(term_id=term_id, display=display, expression=expression)