pytest-given 0.1.0__tar.gz → 0.2.0__tar.gz

pytest_given-0.2.0/AGENTS.md

@@ -0,0 +1,128 @@
+# Agents
+
+## Project overview
+
+See [README.md](README.md) for the user-facing overview, public API, and CLI flags. The rest of this document is contributor-facing.
+
+## Setup
+
+```bash
+uv sync --group dev
+```
+
+**All Python invocations go through `uv run`** — `uv run pytest …`, `uv run python -m …`, `uv run nox …`. There is no system `python` on PATH; bare `python` / `pytest` calls will fail. This applies to one-off commands (running a single test file, REPL exploration) too, not just nox sessions.
+
+**Never prepend `cd <path> &&` to commands.** The working directory is already set to the project root; the `cd` is redundant and triggers a permission prompt.
+
+## Quality gates
+
+`uv run nox` runs the default gate — `format`, `lint`, `mypy`, `test`, `coverage` (a 100% target), `audit` (a `pip-audit` of the locked dependencies). The sessions below are on-demand; list them all with `uv run nox -l`.
+
+- `uv run nox -s examples` regenerates the JSON, HTML, and Markdown files under `examples/coffeeshop/`, `examples/hotel-booking/`, and `examples/file-glossary-booking/`. Run after changes to the renderer, templates, plugin output schema, or any example test file, and commit the updated outputs.
+- `uv run nox -s self_report` regenerates `examples/self-report/` — pytest-given applied to its own backend tests (see [Writing self-report scenarios](#writing-self-report-scenarios)). Run after decorating more tests or changing decorated ones, and commit the updated outputs.
+- **Only commit a regenerated report when its *content* actually changed.**
+  - Every regeneration rewrites `commit_sha` (to current HEAD, including the SHA-pinned source-link URLs), `timestamp`, and `duration_ms` in the JSON and HTML, so a report your change didn't really touch still shows a diff — `git checkout` those files rather than committing the noise.
+  - **Read the `.md` diff first**: the Markdown carries none of those fields, so it is the behavioral delta of your change in prose. An unchanged `.md` doesn't by itself prove the JSON/HTML are noise-only (glossary and story data never surface in the Markdown); a shifted source line does show up, in the `relpath:line::test_name` anchor under every heading.
+  - Regenerate only the reports a change can affect — `examples` narrates `examples/**`, `self_report` narrates `tests/**`. A shifted line number in a decorated backend test is therefore a real self-report change worth committing, even when no example changed.
+- Both regeneration sessions run the narration lint (`--given-lint`; see [Narration lint](README.md#narration-lint) and the [design spec](docs/specs/2026-07-05-narration-lint-design.md)): in `self_report` the backend suite has no intentional failures, so an error finding **fails report regeneration** — a real gate. The `examples` session's intentional failures already return a tolerated exit 1 (`success_codes=[0, 1]`) that masks the lint exit code; there the printed "narration lint" summary is the signal. Keep the backend suite lint-clean; a step the lint mis-flags belongs on the `given_lint_ignore` list, whose entries must each suppress a finding (stale entries fail the run). The rule catalog and the ignore mechanics live in the [authoring skill](src/pytest_given/skills_data/pytest-given-authoring/references/scenarios.md) under "Mechanical counterparts"; the honest-two-phase test an ignored `missing-phase` has to pass is under "Phase structure" in the same file.
+- `uv run nox -s benchmark` generates the large-scenarios suite and renders its JSON + HTML into `benchmarks/` (gitignored). Run it when a change could move report-generation cost; `benchmarks/bench.py` does size sweeps and cProfile runs directly.
+- `uv run nox -s build` builds the wheel + sdist and verifies them the way a consumer would: it checks the wheel carries `py.typed`, the report templates and the bundled skills, then installs it into a throwaway environment and runs a real scenario through it. The in-repo suite imports from `src/`, so it cannot see a packaging regression — this session is the only thing that can. CI runs it on every push; the release workflow runs the same session.
+
+## Releasing
+
+Releases go to PyPI via a manually dispatched [Release workflow](.github/workflows/release.yml), authenticated with Trusted Publishing (no tokens anywhere) and always rehearsed on TestPyPI first. The step-by-step checklist lives in [docs/releasing.md](docs/releasing.md).
+
+The short version: bump `version` in `pyproject.toml` and add a matching `## [x.y.z]` section to `CHANGELOG.md`, land it on `main` (a PR is optional — CI gates direct pushes too), dispatch with `testpypi`, run `uv run nox -s check_release -- testpypi`, then dispatch with `pypi` and re-check with `uv run nox -s check_release`.
+
+## Architecture
+
+`src/pytest_given/` is five library subpackages plus two entry points, with a
+strict dependency direction (convention, not lint-enforced):
+
+```
+model/                     the leaf — schema, serde, errors, shared text rules
+capture/  lint/  report/   each on model/ only, never on each other
+grouping/                  on model/ + capture/
+plugin/   cli/             the entry points; may import all five, and hold
+                           nothing the five could
+```
+
+**Every module has a docstring saying what it is for and why it is shaped that
+way.** That is where the detail lives, and it stays true because it sits next
+to the code — read it before changing a module. What no filename tells you:
+
+- `grouping/` — the parametrize pass: a scenario's cases collapsed into one
+  narrated tree plus a parameter table, refusing the authoring forms that would
+  make that tree lie. Runs at session finish *before* the sinks are written, so
+  a bare `pytest` failing on one is the point, not a side effect.
+- `plugin/__init__.py` is the hook surface pluggy registers — the `pytest11`
+  entry point is the package, and pluggy scans a module's attributes for
+  `pytest_*` names, so the re-exports there *are* the registration.
+- `capture/` imports pytest nowhere, so all of it is unit-testable without a
+  session; a stray step warns with `model.PytestGivenWarning`, not pytest's.
+- `Glossary` exists twice on purpose: `model/schema.py` holds the storage the
+  report carries and serde rebuilds, and `capture/glossary.py` subclasses it
+  with the registration API, which needs a caller source location that the leaf
+  may not reach for. `pytest_given.Glossary` is the subclass; everything
+  internal annotates the base.
+- Each package exposes the *whole* job, not its parts: `report.emit_sinks`
+  (render → write → discard-on-failure, so a failure leaves no half-written
+  report) and `lint.run_lint`. Both entry points go through them, which is what
+  keeps `pytest-given report` behaving like the plugin.
+
+`tests/` splits `unit/` (no pytest session needed) from `integration/`, which drives the plugin end to end through `pytester` inner runs (enabled by the root `conftest.py`). Narration written inside an inner run belongs to *that* run's collector — only the outer, decorated test reaches the self-report.
+
+The public API is re-exported from `__init__.py` and documented in the skill's
+[references/api.md](src/pytest_given/skills_data/pytest-given-authoring/references/api.md).
+
+### Step text & placeholders
+
+The authoring forms (t-string vs `Template` vs plain string, and where each is rejected) are documented in the skill's [references/api.md](src/pytest_given/skills_data/pytest-given-authoring/references/api.md); design rationale in the [design spec](docs/specs/2026-05-23-structured-step-text-design.md).
+
+## Handling report output
+
+Outputs are opt-in; a bare `uv run pytest` writes nothing. The workflow for reading a run's narration (`--given-md`), querying the JSON report with `jq` by tag/term/status, re-rendering a saved run, and the bare-flag-order trap lives in the [navigating skill](src/pytest_given/skills_data/pytest-given-navigating/SKILL.md).
+
+## Report testing
+
+Any change to `report/templates/` (Jinja, CSS, `app.js`) or the `narration` filter in `html_renderer.py` **must** be Playwright-verified before commit — Python-side regex tests on rendered HTML do not catch broken Alpine expressions, malformed `:class` bindings, or other runtime browser issues (the substring matches even when the attribute is unparseable). Open e.g. `examples/coffeeshop/coffeeshop.html` (regenerate via `uv run nox -s examples`) with the Playwright MCP server, check `browser_console_messages` for errors after init, then drive the changed surface (hover, click, URL hash). Use `browser_snapshot` (not screenshots) to read page content and interact with elements.
+
+- **Don't write Python tests that pin frontend markup** (specific class names, wrapper structure, inline-handler shape, SVG strings). They check implementation details, not behavior, and rot the moment the renderer is refactored. The project has no JS-side UI tests; Playwright is the only verification for frontend concerns. Python tests stay on the renderer's data-shaped contract (what `data-param` value, which scenario IDs, which counts) — not on how the markup is assembled.
+- **Don't TDD frontend changes** for the same reason: a failing markup assertion isn't proving the bug exists in the browser, and a passing one isn't proving the fix works. Apply the change, regenerate `examples/`, drive it in Playwright, capture the result.
+
+- The report targets desktop only — assume a minimum viewport width of ~900px. No mobile/responsive layout needed.
+- Traceback display and header metadata formatting are known limitations, not current priorities.
+- Never save Playwright screenshots into the project directory. Use `/tmp/` or omit the `filename` parameter.
+
+**Setup and known traps** (`.mcp.json`, the `file://` page cache, browser installs) live in [docs/playwright-setup.md](docs/playwright-setup.md). `.mcp.json` is read at **session start**, so check that the `browser_*` tools exist before planning a task that ends in Playwright verification.
+
+## Writing self-report scenarios
+
+The narration rules live in the **`pytest-given-authoring` skill** — whose canonical source is [src/pytest_given/skills_data/](src/pytest_given/skills_data/pytest-given-authoring/SKILL.md) — every link in this document points there. Contributor agents auto-discover the mirrored copy under `.claude/skills/`, and downstream projects get it via `pytest-given skills install`. After editing the canonical copy, regenerate the committed copy with `uv run pytest-given skills install` and commit both (a sync test fails otherwise).
+
+**The skill is documentation with the same sync duty as the README.** A change to the public API surface or its rules updates the README *and* the skill's [references/api.md](src/pytest_given/skills_data/pytest-given-authoring/references/api.md) (which downstream agents rely on instead of the README — it ships in the wheel, version-matched); a change to narration/lint semantics updates [references/scenarios.md](src/pytest_given/skills_data/pytest-given-authoring/references/scenarios.md) and friends. No mechanical check catches content drift between README and skill — treat "does the skill need this too?" as part of every user-facing change.
+
+What is specific to this repo's self-report:
+
+- The glossary handle is `pg` — `GLOSSARY.md` loaded as a `FileGlossary` in `tests/conftest.py` via `tests/ubiquitous_language.py`. Term-rename mechanics live under [Conventions](#conventions); regeneration and lint gating under [Quality gates](#quality-gates).
+- **New or changed user-facing behavior needs a scenario, not just a test** — otherwise the behavior is invisible in the report. Decorate the test that best *states* the rule, one per rule, not per branch; the edge cases around it stay plain. Two gaps to check for: a rule the [CHANGELOG](CHANGELOG.md) announces that no scenario names, and a [GLOSSARY.md](GLOSSARY.md) row *asserting* behavior (`Templatize`, `Parameter table`) that no scenario demonstrates.
+
+## Conventions
+
+- Use the canonical vocabulary from [GLOSSARY.md](GLOSSARY.md) in prose as well as code — docs, skill references, and specs say the official term (`term ref`, not a paraphrase like "narrated term"). Naming and rename mechanics live in the skill's [references/glossaries.md](src/pytest_given/skills_data/pytest-given-authoring/references/glossaries.md); here, a rename lands in one commit (glossary row, `pg\[` references, implementation naming) plus a regenerated `uv run nox -s self_report`. Adding a term is safe, but still regenerate.
+- Avoid `Any` — use precise types, generics, `TYPE_CHECKING` imports, or `ContextVar[T]` over untyped `threading.local`.
+- Use `NewType` for domain-specific IDs (e.g., `NodeId`) and PEP 695 `type` statements for aliases. Avoid raw complex types like `dict[str, tuple[list[str], list[Any]]]` — introduce named types instead.
+- Only module-level imports — no inline/function-level imports.
+- **pytest config lives in `[tool.pytest]`** — native TOML mode since pytest 8.4/9.0, where lists are real arrays rather than newline-separated strings. `[tool.pytest.ini_options]` is the legacy INI-compat table; **never add it alongside** — pytest raises `UsageError` if both are present. New `addini` options take native types (a `type='linelist'` ini takes a TOML array).
+- Cross-platform: plugin and tests must pass on native Windows, macOS, Linux, and WSL (Linux interpreter over a `/mnt/<drive>` Windows checkout). Never hardcode a path separator or assume POSIX semantics — go through `pathlib`, `as_posix()` for stored/serialized paths, resolve before comparing. Path-form folding is confined to `capture/source.py` (mechanics in its docstrings; the why, and how to run one checkout from both Windows and WSL without the venvs colliding, in [docs/wsl-development.md](docs/wsl-development.md)). Only tests asserting WSL `/mnt`-absolute behavior may `skipif(sys.platform == 'win32', …)` — native-Windows pathlib reads `/mnt/<drive>` as drive-relative, not absolute — everything else passes on all four targets.
+- Relative imports inside the package throughout — `from .schema import Scenario` for siblings, `from ..model import Scenario` across subpackages (always through the subpackage root, never into its submodules). Tests use absolute imports and may reach into any internal path. The dependency direction those imports must respect is under [Architecture](#architecture).
+- Prefer `assert` over `# pragma: no cover` for invariant guards. Asserts document the invariant and fail loudly if violated; pragmas hide the line and silently bail. Reserve `# pragma: no cover` for code that genuinely cannot be exercised by a test (e.g. `if __name__ == '__main__':` script entry).
+- Step-down rule: callers before callees, public before private. Read each file top-down from high-level API to implementation details.
+- TDD: write tests first
+- Commit messages: single line, no co-author trailers, no leading file/area labels like `TODO:` or `README:` — just describe the change ("note example cleanup as todo", not "TODO: note example cleanup"). Conventional-commit-style scope prefixes like `docs:` / `examples:` / `renderer:` are fine when they add information.
+- Keep commits coherent: each commit should represent one logical change. Don't split "do X", "tests for X", and "review-fixup for X" into separate commits — squash them before pushing. Don't bundle unrelated changes either.
+- **A user-facing change adds its `CHANGELOG.md` entry in the same commit**, under `## [Unreleased]`, in the fitting Keep a Changelog category (each category appears at most once per version — extend the existing heading rather than adding a second one). User-facing = public API, CLI flags, report output, lint rules, bundled skills; internal work (refactors, tests, CI, contributor docs) gets no entry. Release-time version bumps live under [Releasing](#releasing).
+- **One sentence per entry**, written for someone upgrading the package: name the symbol, flag, or surface, and say what changed. Only a breaking change earns more — the migration it needs. Cut the rest: rationale, measurements, before/after detail, and anything the reader would discover the moment they look at the thing. Visual and interaction polish is worth mentioning but not itemizing: give it one short collective bullet per release ("the sidebar and its chips are visually tidied"), never a bullet per restyled element. Accessibility fixes are the exception — they stay on their own line, since they change who can use the thing. If a change isn't worth an upgrader's attention at all, it gets none. When in doubt, the shorter entry is the right one.
+- Plan files under `docs/superpowers/plans/` are scratch artifacts — never commit them. Spec files under `docs/specs/` are committed.
+- New specs land under `docs/specs/proposed/`. When a spec's implementation lands, `git mv` it up one level into `docs/specs/` in the same commit, and fix its relative links in the same edit — a `../`-prefixed link to a sibling spec resolves into `docs/` once the file moves. `ls docs/specs/proposed` is the canonical list of outstanding design work.
+- Always run `uv run nox` (or at minimum `uv run nox -s format lint mypy test`) before committing

pytest_given-0.2.0/CHANGELOG.md

@@ -0,0 +1,310 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The release workflow reads the section matching the version in `pyproject.toml`
+and uses it as the GitHub Release body, so each version needs a heading of the
+form `## [x.y.z] - YYYY-MM-DD`.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+
+- `pytest_given.PytestGivenWarning` is a top-level export, and a step or
+  `attach()` recorded in a test without `@scenario` now warns with it instead of
+  `pytest.PytestWarning`.
+- `--given-title=TEXT` (or the `given_title` ini) names the report, replacing the
+  rootdir name.
+- A parametrized scenario's parameter table now carries a typed column per varying
+  value — `param`, `derived`, or `attachment` for a varying attachment payload —
+  rather than one column per parametrize name.
+- `@scenario(group_parametrized=False)` declines the grouping and emits each case
+  as its own scenario, titled by its parametrize id.
+- The HTML report's sidebar gains **Terms** as a third browse axis, and all three
+  axes — Tags, Terms, Modules — now filter the Scenarios view the same way, with
+  each active filter carried in the URL.
+- The sidebar can be ordered by group size as well as by name, and resized by
+  dragging its seam or with the arrow keys.
+- A selected activity in the Stories view offers **Open in Scenarios**, filtering
+  the Scenarios view down to the scenarios covering it.
+
+### Changed
+
+#### CLI
+
+- **Breaking.** `--given-lint` is a plain boolean flag: write `--given-lint` and
+  `--no-given-lint` instead of `--given-lint=true` / `--given-lint=false`. Either
+  form still overrides the `given_lint` ini for one run.
+
+#### Authoring API
+
+- **Breaking.** Step narration must now be uniform across parametrize cases;
+  these fail the run with `PytestGivenError`, writing no report, instead of
+  quietly reporting case 1:
+
+  - a plain `str` (usually an f-string) that renders differently per case;
+  - a varying interpolation that is not a bare name (`t"{cup_size * 0.01}"`,
+    `t"{m.balance}"`);
+  - a t-string narrating a parametrize name that no longer holds the case's
+    value — either a local rebound it, or the body mutated it in place;
+  - a step whose set of `attach` labels differs between cases;
+  - a glossary term ref that names a different term or reads differently between
+    cases, including one bound to a parametrize column;
+  - passed cases that narrate different templates altogether.
+
+  Every one but the last is fixed by binding the varying part to a local and
+  narrating it with a t-string, keeping labels and term refs constant; varying
+  content belongs in the new `attachment` column. The last needs
+  `@scenario(..., group_parametrized=False)`, giving each case its own scenario.
+- **Breaking.** `attach()` now takes a plain `str` label; a t-string label raises
+  `PytestGivenError` — use an f-string.
+- **Breaking.** `attach()` called with no step open now raises `PytestGivenError`
+  instead of silently discarding the payload; move the call inside the step it
+  belongs to.
+- **Breaking.** `activity(..., id=N)` is now `activity(..., activity_id=N)`; the
+  `Activity.id` field itself is unchanged.
+- **Breaking.** `FileGlossary` is now a `Glossary` subclass rather than a wrapper
+  around one, so its `.glossary` attribute is gone — use the `FileGlossary`
+  itself wherever that attribute was passed.
+- A glossary term placed in an activity slot its declared kind forbids now raises
+  `PytestGivenError` when `activity(...)` is built rather than at session finish.
+- A glossary file whose table has a header and separator but no data rows now
+  says so, instead of reporting that no table was found.
+- A `FileGlossary` whose columns are all named now skips a Markdown table that
+  carries none of those names, so a glossary file may hold prose tables beside
+  the glossary; a table carrying some of them still raises, as does any table
+  under an index-based column spec.
+- `@scenario(activities=...)` now rejects a `str` and non-`int` members with a
+  `TypeError`.
+- `@scenario` now returns the test function itself rather than a wrapper, so the
+  test keeps its own signature.
+
+#### Plugin and run behavior
+
+- An unknown `given_source_link` preset is now a `UsageError` raised before the
+  suite runs.
+- The collection-time `@scenario` checks now report as a `UsageError` instead of
+  an `INTERNALERROR` traceback.
+- The narration lint summary prints each finding's location in its own column
+  rather than appended to the message.
+- `pytest-given` with no subcommand, and `pytest-given skills` with no
+  subcommand, now print that parser's usage and exit 2 instead of the root help
+  and exit 1.
+
+#### Report content (all formats)
+
+- **Breaking (JSON report).** `parameters.names` becomes `parameters.columns`
+  (`{id, name, kind}`), cells may hold an attachment object, placeholder parts
+  gain `column_id`, term-ref parts lose `param_column`, and a grouped step's
+  `narration.text` is the template rather than case 1's rendering.
+- **Breaking (JSON report).** A step no longer carries `status` or `error`;
+  failure lives on the scenario and on the parameter table's cases. A consumer
+  reading `step.status` should read `scenario.status` instead.
+- The Markdown report now shows a scenario's failure reason — the message and the
+  failing frame — under the scenario, and under the parameter table for each
+  failed case.
+
+#### HTML report
+
+- The browse sidebar leads with **Modules** and renders them as a collapsible
+  package tree whose nodes filter by path prefix; it no longer lists individual
+  scenarios under each group.
+- The report's colors are retuned into one system — a term ref in a step or a
+  scenario title reads as a word under a light wash rather than a bordered pill
+  (the Glossary view keeps its pills), and column colors are generated per
+  column — and the sidebar, its filter chips and the attachment badges are
+  tidied along with it.
+- The report opens and filters substantially faster on large suites, and its file
+  is smaller — a term reference now points at its glossary entry instead of
+  repeating the entry's definition, which takes about 18% off a term-heavy
+  report.
+- A glossary term referenced only in a `@scenario` title now contributes an
+  instance to the Glossary view, where it previously counted toward the term's
+  scenario tally while showing no instance.
+
+#### Bundled skills
+
+- The authoring and reviewing skills gain the report mechanics their rules depend
+  on, a symptom index, a completeness audit, the full lint rule catalog, and
+  guidance for sparser tagging.
+
+### Removed
+
+- **Breaking.** The `divergent-case-structure` lint rule; delete any
+  `given_lint_rules` or `given_lint_ignore` entry naming it, which would
+  otherwise fail config parsing.
+
+### Fixed
+
+#### Authoring API
+
+- Parametrize cases that claim different step activities now say so, instead of
+  reporting the more drastic "a different step structure".
+
+- A `@given` fixture scoped wider than `function` no longer loses its step when
+  the first test to use it has no `@scenario`.
+- `@given`/`@when`/`@then` are signature-preserving, so a decorated helper stays
+  callable to a type checker (was: `"StepDecorated" not callable`).
+- `@given(...)` above `@pytest.fixture` now raises and names the fix, instead of
+  surfacing as `fixture '<name>' not found`.
+- `@scenario(activities=...)` is now typed `int | Sequence[int] | None`, so a
+  bare `activities=2` type-checks.
+- `@scenario(activities=...)` with an unknown id, or without `story=`, is
+  rejected at the decorator rather than at collection.
+- A `-k`- or `--deselect`-narrowed run no longer fails on an authoring error in
+  a scenario it did not select.
+- Glossary term handles are now hashable, and equal for the same term whichever
+  accessor produced them.
+- A `when_then` step in a test without `@scenario` now points its warning at the
+  test rather than at pytest-given's own module.
+
+#### Narration lint
+
+- A `given_lint_ignore` entry beginning with a Windows drive letter
+  (`c:/repo/tests/t.py::test_x`) is no longer rejected as an unknown rule prefix.
+
+- A rule configured `off` no longer runs; levels were applied only after every
+  rule had already produced its findings.
+- A scenario tag with no ASCII alphanumerics (`tags=['日本語']`) no longer takes
+  the run down with a traceback from `tag-shadows-term`.
+
+#### Report
+
+- `pytest-given report` reports an unreadable input as an error instead of a
+  traceback (a directory raised `IsADirectoryError` through the console script).
+- A JSON report with an out-of-range scenario `status` or term `kind` is
+  rejected by name, instead of crashing a renderer with a bare `KeyError`.
+- A `<br>` inside an inline code span in a glossary definition renders as text
+  rather than as a line break.
+- The Terms browse axis no longer lists a term the selected glossary does not
+  hold.
+
+#### Plugin and run behavior
+
+- A `--given-json`/`--given-html`/`--given-md` path that could not be a report
+  file is now refused before the suite runs, instead of a bare flag swallowing a
+  following test path and overwriting — or, on a failed run, deleting — it.
+- `pytest-given report` now discards a stale report when the *render* fails, not
+  only when the write does.
+- `pytest-given report --source-link` is now validated on a `--format md` run
+  instead of being accepted and ignored, and an unknown preset is reported under
+  the name the user typed.
+- A `git` on PATH that cannot be executed no longer fails the run.
+- A nested in-process pytest run that dies while parsing its arguments no longer
+  strands the outer session's captured rootdir, which silently dropped every
+  later step's source anchor.
+- `@given`/`@when`/`@then` on an `async def` helper now records around the
+  awaited body, and async generator fixtures are handled too.
+- The narration lint now inspects `async def` step helpers, whose bodies were
+  invisible to every AST rule.
+- An explicit `--given-source-link=` now disables source links instead of falling
+  through to the `given_source_link` ini.
+- A finished scenario no longer leaves its collector — and every scenario and
+  step it recorded — reachable from a process-global for the rest of the process.
+- An error-level lint finding no longer overwrites a more specific exit code, so
+  an interrupted or nothing-collected run keeps reporting as one.
+- A report that cannot be written into an unwritable directory now reports
+  through the terminal summary instead of escaping as a bare traceback.
+- `pytest-given report` and `pytest-given skills install` now report a failed
+  write as a CLI error, and a failed `report` write discards the previous run's
+  report rather than leaving it to read as current.
+- `pytest-given report` now reports a bad input file — missing, unparsable, or
+  JSON that is not a pytest-given report — as a CLI error instead of a traceback,
+  as does an unknown `--source-link` preset.
+- A fixture that raises after its `yield` now fails the scenario it tore down,
+  instead of leaving it green in a report pytest counted as an error.
+- An error-level narration-lint finding now counts as an error in the run's
+  summary line.
+- Every failure building or writing a report — a suite reaching two glossaries, a
+  term used in incompatible slots, an unusable source-link template, an
+  unwritable output path — now surfaces as a terminal summary and a failing exit
+  code, where only grouping errors did.
+- The sinks are now rendered in full before any is written, and a failure on
+  either side discards all of them.
+
+#### Report content (all formats)
+
+- A parametrized scenario whose cases all skipped now keeps its skip reason
+  instead of reporting `skipped` with none.
+- A parameter row whose cell count disagreed with the table's columns silently
+  truncated in the HTML report; it now fails the same way it already did in
+  Markdown.
+
+- A parametrized scenario now keeps its place in source order instead of moving
+  below every unparametrized one.
+- A glossary term written as a code span keeps the markup inside it, so
+  `` `a*b*c` `` canonicalizes to `a*b*c`.
+- A parameter-table cell now reads the way the step pointing at it read, carrying
+  the interpolation's own format spec and, under `indirect=True`, the bound test
+  argument.
+- A `Template` narration's `text` is now what its parts render, so the report's
+  search box and `jq` queries match what the page displays.
+- The grouped step tree now comes from the first case that *passed*, where a
+  skipped case 1 used to render an empty tree.
+- A parametrize value that is a glossary term instance now narrates as its
+  display rather than the whole `Glossary` dataclass repr — in a step's
+  `Template` slot, in a scenario name, and in an
+  `Annotated[..., given(Template(...))]` parameter label.
+
+#### HTML report
+
+- Two test files sharing a basename across directories no longer abort the HTML
+  report; the scenarios' `#scenario=` slugs gain directory components instead.
+- A `#view=stories`, `#view=glossary` or `#term=` link opened against a report
+  that has no such tab now falls back to the Scenarios view.
+- The Glossary view's kind headings and their term counts now follow the search
+  and definition filters, and a filter matching nothing says so.
+- Content reaching past a scenario card's right edge is no longer clipped: a wide
+  parameter table and an attachment payload scroll, a source path and a
+  traceback's frame location wrap, and the source link no longer overlaps the
+  card's last element.
+- Jumping to a scenario from a story activity, or to a term's scenarios from the
+  Glossary tab, now clears filters that would hide the target; the filters in a
+  `#scenario=` deep link still win.
+- Accent-colored text and the parametrize column colors now meet WCAG AA, and
+  term kinds stay distinguishable for red-green color blindness.
+- The report is operable from the keyboard: status pills, browse-axis and
+  browse-tree rows, tag pills, story sidebar entries, activity and attachment
+  badges, and every expand/collapse chevron are now real buttons, and the view
+  tabs report which one is selected.
+- A step pinned with `given(..., activity=N)` now covers an activity regardless
+  of its term count; an under-anchored activity previously still rendered as
+  "not coverage-tracked".
+
+#### Bundled skills
+
+- The bundled skills are corrected against the shipped behavior.
+
+## [0.1.0] - 2026-08-08
+
+First public release.
+
+### Added
+
+- `@scenario` decorator plus `given` / `when` / `then` step blocks, usable as
+  both context managers and decorators, including on fixtures.
+- Self-contained interactive HTML report (`--given-html`), Markdown report
+  (`--given-md`), and JSON report (`--given-json`). The HTML bundles Alpine.js
+  and needs no server or external assets.
+- Structured step text: plain strings, `Template` objects, and t-strings
+  ([PEP 750](https://peps.python.org/pep-0750/)), with parameter interpolation
+  rendered as highlighted values.
+- `attach()` for text and JSON attachments on a step.
+- Domain Storytelling support: ubiquitous-language glossaries (inline or
+  Markdown-backed via `FileGlossary`), Domain Stories, and story coverage.
+- Narration lint (`--given-lint`) with a configurable rule catalog via
+  `given_lint_rules` and `given_lint_ignore`.
+- `--given-source-link` with `vscode`, `cursor`, `zed`, `pycharm`, and `github`
+  presets for jumping from a report step to its source.
+- `pytest-given` console script: `report` to re-render a saved JSON report, and
+  `skills install` to mirror the bundled agent skills into a project's
+  `.claude/skills/`.
+- Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
+  the wheel and version-matched to the plugin.
+
+[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/nwilbert/pytest-given/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/nwilbert/pytest-given/releases/tag/v0.1.0

{pytest_given-0.1.0 → pytest_given-0.2.0}/GLOSSARY.md

@@ -2,7 +2,7 @@
 
 Canonical vocabulary for pytest-given. Use these terms in code, docs, commit messages, and conversation; flag inconsistencies in review.
 
-This glossary covers pytest-given's own bounded context. The terminology a *user's* test suite adopts (the domain the user is testing — e.g., the coffee domain in `examples/test_examples.py`) is a separate concern.
+This glossary covers pytest-given's own bounded context. The terminology a *user's* test suite adopts (the domain the user is testing — e.g., the coffee domain in `examples/coffeeshop/test_coffeeshop.py`) is a separate concern.
 
 **Update rule:** rename or repurpose a term → update this file in the same commit.
 
@@ -11,8 +11,8 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
 | Term | Meaning |
 |---|---|
 | **Scenario** | A test function decorated with `@scenario(...)`. Not every pytest test is a scenario — undecorated tests are tolerated but not collected. |
-| **Step** | A unit of narration: a `with given(...)` / `when(...)` / `then(...)` block, or the root recording from a step fixture. Steps nest. Each carries a phase, text, status (`'passed'` by default; set to `'failed'` on the step where a scenario fails, for highlighting in the report), optional error, attachments, and children. |
-| **Narration** | The human-readable text on a step or scenario name. Modeled as a `Narration` dataclass bundling a flat rendered `text: str` with a `parts: list[NarrationPart]` (empty for plain-string authoring; populated when the source was a t-string or `pytest_given.Template`, with `NarrationLiteral` / `NarrationValue` / `NarrationPlaceholder` pieces). The structured form lets the templatizer and renderer treat parametrize-bound values specially without regex tricks. |
+| **Step** | A unit of narration: a `with given(...)` / `when(...)` / `then(...)` block, or the root recording from a step fixture. Steps nest, and each carries a phase, narration, attachments and children — but no status or error of its own: a failure is recorded on the *Scenario*, and per *Case* on the *Parameter table*, which is where both renderers read it. |
+| **Narration** | The human-readable text on a step or scenario name. A `Narration` bundles the flat rendered `text` with `parts` — empty for plain-string authoring, and for a t-string or `pytest_given.Template` a list of `NarrationLiteral` / `NarrationValue` / `NarrationPlaceholder` / `NarrationTermRef` pieces. The structured form lets the templatizer and renderer treat parametrize-bound values specially without regex tricks. |
 | **Phase** | The category of a step: `given`, `when`, or `then`. A step has exactly one phase. |
 | **when_then** | A step-authoring helper that emits a `when` action and its `then` outcome as two sibling steps from a single `with` block. Used mainly to narrate an expected raise (`with when_then('the action', 'the error is raised'), pytest.raises(...)`), so the action and its outcome stay distinct steps. |
 | **Tag** | Free-form string label attached via `@scenario(name, tags=[...])`. Used by the report's filter UI. |
@@ -24,9 +24,9 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
 |---|---|
 | **Parametrized scenario** | A `@scenario`-decorated test that also carries `@pytest.mark.parametrize(...)`. Produces multiple scenario records during a run; pytest-given groups them. |
 | **Case** | One row of a parametrized scenario — a single tuple of parameter values, its status, and any error. |
-| **Parameter table** | The per-scenario grouping of column names + cases. Appears in the report below the grouped-template steps. |
-| **Group** | Collapsing the N scenario records of a parametrized scenario into one logical scenario carrying a parameter table. Scenarios group when they share the same name and module. |
-| **Templatize** | Derive the grouped-template step text from the first case, so the report shows a single set of steps with `{name}` placeholders that the parameter table fills in per case. Non-first cases' structured text is discarded. |
+| **Parameter table** | The per-scenario grouping of typed columns + cases. A column is a `param` (a `@pytest.mark.parametrize` input), a `derived` (a narrated value that varies across cases) or an `attachment` (an attachment whose payload varies). Appears in the report below the grouped-template steps. |
+| **Group** | Collapsing the N scenario records of a parametrized scenario into one logical scenario carrying a *Parameter table*. Cases group when they share both the same name and the same *Node ID* without its parametrize tail — one test function; two same-named scenarios on different test functions stay separate. `@scenario(group_parametrized=False)` declines the merge, so each case lives on as its own scenario. |
+| **Templatize** | Derive the grouped-template step text by comparing every comparable case: what all of them share stays inline, and anything that varies becomes a `{name}` placeholder or attachment badge pointing at a parameter-table column. The baseline tree comes from the first passed case, and every other passed case must narrate that same template. |
 
 ## Fixtures and recording
 
@@ -34,14 +34,14 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
 |---|---|
 | **Step fixture** | A pytest fixture whose function is wrapped with `@given(text)`. Only `@given` is allowed on fixtures; `@when` / `@then` are rejected. |
 | **Plain fixture** | A pytest fixture without a pytest-given decorator. Used by tests but produces no step in the report. |
-| **Fixture recording** | A captured subtree of steps + attachments produced while a step fixture is being set up (and, for generator fixtures, torn down). Stored keyed by fixture-instance identity. |
+| **Fixture recording** | A captured subtree of steps + attachments produced while a step fixture is being set up. Stored keyed by fixture-instance identity. A generator fixture's teardown records nothing — it refuses steps and attachments. |
 | **Graft** | Attaching a fixture recording into the active scenario's step tree at the moment its host test starts. |
 
 ## Collector state
 
 | Term | Meaning |
 |---|---|
-| **Collector** | The module-level singleton that accumulates scenarios, fixture recordings, and parameter info during a pytest session. Reset at the start of each session. |
+| **Collector** | The per-session object accumulating scenarios, fixture recordings, and parameter info, published through a `ContextVar` so a nested run can displace and restore it. |
 | **Active scenario** | The scenario currently being recorded into; tracked by node ID. |
 | **Node ID** | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). Used as a key throughout the collector. |
 | **Step stack** | The chain of currently-open steps; entered by `with given(...)`, popped on exit. Mirrored inside a fixture recording while a fixture body is running. |
@@ -51,10 +51,19 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
 | Term | Meaning |
 |---|---|
 | **Report** | The output artifact: a JSON data file and optional self-contained HTML and Markdown renderings derived from it. The JSON is the source of truth. |
-| **Renderer** | Converts a JSON report into a self-contained HTML page. |
+| **Renderer** | Converts a JSON report into a rendering — a self-contained HTML page or a Markdown document. |
 | **Parameter coloring** | Each parametrize column gets a stable highlight color; placeholders and matching values share that color wherever they appear in step text and the parameter table. |
-| **Value highlight** | A neutral highlight applied to t-string interpolation values that don't correspond to a parametrize column (e.g., a computed expression like `price * 1.2`). |
-| **Source link** | A clickable file:line anchor on a scenario card. Resolved from the `given_source_link` config (preset name like `vscode` / `github`, or a raw URL template). Captured per-scenario as a `SourceLocation` (POSIX relpath + 1-indexed line) from `pytest.Item.location`. Disabled by default. |
+| **Value highlight** | A neutral highlight applied to t-string interpolation values that don't correspond to a parametrize column and are constant across every case (e.g., a computed expression like `price * 1.2`). One that varies becomes a `derived` column instead. |
+| **Source link** | A clickable file:line anchor on a scenario card, a story panel, or an expanded glossary term card, resolved from the `given_source_link` config — a preset name like `vscode` / `github`, or a raw URL template. Captured as a `SourceLocation` (POSIX relpath + 1-indexed line) from `pytest.Item.location` for a scenario, from the declaration site for a *Story* or *Term*. Disabled by default. |
+
+## Narration lint
+
+| Term | Meaning |
+|---|---|
+| **Narration lint** | The `--given-lint` pass that checks recorded scenarios against the *Lint rule* catalog once the *Report* model is built. It enforces the structural subset of the narration conventions — it cannot check whether a *Step*'s text is semantically true. |
+| **Lint rule** | One named check, carrying a surface and a default *Severity*. A `runtime` rule reads the recorded scenarios; an `ast` rule parses the step bodies' source. The catalog in `lint/base.py` is data, so severities, config validation and docs stay in sync with one table. |
+| **Finding** | One *Lint rule* firing on one subject: the rule id, the *Severity* it fired at, the subject, a *Source link* location and a message naming the offender. |
+| **Severity** | A *Lint rule*'s level — `off`, `warn` or `error` — defaulted by the catalog and overridable per rule via `given_lint_rules`. Only `error` fails the run; `warn` reports in the terminal summary; an `off` rule is not evaluated at all. |
 
 ## Domain Storytelling
 
@@ -64,21 +73,21 @@ The Domain-Driven Design layer atop the core surface. All terms here are optiona
 |---|---|
 | **Glossary** | The Ubiquitous-Language concept — the shared vocabulary a domain speaks in — and the class that realizes it: `Glossary()`, with `.actor(...)`, `.work_object(...)`, `.verb(...)` registration methods and `g('foo')` (declare-or-get a kindless term, optional `definition=`) / `g['foo']` (get-only, raises on unknown) accessor forms. |
 | **File glossary** | A glossary loaded from a Markdown file, via the `FileGlossary(path)` class. It parses all GFM pipe tables in the file into the same inner `Glossary` model; terms are accessed by name (`g['Guest']`, case-insensitive). *Kind inference* fills in term kinds post-collection from activity *slot* positions when no explicit `kind_column` is configured. |
-| **Deferred term** | A term obtained before its kind is known — the `DeferredTermHandle` returned by the code glossary (`g('foo')` declare-or-get, `g['foo']` get-only) and by a *file glossary* (`g['Guest']`). One handle type serves all kinds (unlike the eager Actor/Work Object/Verb handles); the kind stays `None` until *kind inference* runs. |
+| **Deferred term** | A term handed over before its kind is settled — what `g('foo')` and `g['foo']` on a code glossary return, and every *file glossary* lookup. The handle is the same `TermHandle` the typed registrations (`g.actor(...)` and friends) hand back; `declared_kind is None` is what marks the deferral. The deferral is in the handing over, not the term: a row with an explicit `kind_column` arrives through the same handle already kinded, while the rest stay `None` until *kind inference* runs. |
 | **Term** | A registered glossary entry: an Actor, Work Object, Verb, or kindless term. Each carries an id (slug), a canonical name, a kind (`None` when kindless), and an optional definition (`str | None`, `None` when undefined). |
-| **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). Renders with the actor pill style. |
-| **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). Renders with the work-object pill style. |
+| **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). Carries the actor kind color: a wash in narration, a pill in the Glossary view. |
+| **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). Carries the work-object kind color: a wash in narration, a pill in the Glossary view. |
 | **Verb** | A glossary term for an action (e.g., *book*, *confirm*). Verbs accept inflections — calling `book('books')` records *books* as a surface form of the canonical *book*. |
-| **Term ref** | An occurrence of a term inside narration. Modelled as `NarrationTermRef` in step text and as `ActivityTermRef` inside activity prose. |
+| **Term ref** | An occurrence of a term inside narration. Modeled as `NarrationTermRef` in step text and as `ActivityTermRef` inside activity prose. |
 | **Instance** | A named refinement of an Actor or Work Object (e.g., `guest('Alice')` is an instance of the *Guest* actor). Instances aggregate in the Glossary tab's refs block. |
 | **Inflection** | A surface form of a Verb other than its canonical name (e.g., *searches for* as an inflection of *search*). Reported under "Also used as:" in the Glossary. |
-| **Story** | A named flow modelled as a sequence of activities. Constructed by `story('Title', [activity(...), ...])`. Stories are first-class report tabs and the unit of coverage. |
+| **Story** | A named flow modeled as a sequence of activities. Constructed by `story('Title', [activity(...), ...])`. Stories are first-class report tabs and the unit of coverage. |
 | **Activity** | One row in a story — typically `actor + verb + work_object` plus optional connective words. Constructed by `activity(...)`. |
-| **Activity Part** | The two-variant union making up an activity's prose (`ActivityPart` = `ActivityTermRef | ActivityWord`): `ActivityTermRef` (a reference to a glossary term — actor, work object, or verb; kind resolved via the glossary) and `ActivityWord` (a bare path word — a node label or an edge connective; carries no kind or id, is never classified by inference, and never appears in the glossary — distinct from a kindless/undefined term, which has an id and is tracked). |
+| **Activity Part** | The two-variant union making up an activity's prose (`ActivityPart` = `ActivityTermRef` or `ActivityWord`): a reference to a glossary term, whose kind resolves via the glossary, or a bare path word — a node label or edge connective that carries no kind or id, is never classified by inference, and never reaches the glossary. That last is what separates it from a kindless term, which has an id and is tracked. |
 | **Path** | A branching segment inside a story — `path(...)` lets alternate activity sequences share a prefix. |
 | **Slot** | A position role in an activity path, from its node/edge alternation: position 0 is the actor slot, odd positions are verb slots, and even positions ≥ 2 are noun slots. Slots drive both path validation and *kind inference*. |
 | **Scenario↔activity binding** | The link between a scenario (or step) and one or more story activities. Carried by `@scenario(story=, activities=)` and the `activity=` kwarg on `given`/`when`/`then`. |
-| **Coverage** | The "did this scenario touch that activity" relation. Computed by the *A_refs ⊆ S* rule: an activity is covered when its set of term references (as identities, with a canonical fallback) is a subset of a single step's term-reference identities — matching is per step, not against the union across steps. A step can also cover an activity explicitly via the `activity=` pin, regardless of its narration. |
+| **Coverage** | The "did this scenario touch that activity" relation. Computed by the *A_refs ⊆ S* rule: an activity is covered when its set of term references (as identities, with a canonical fallback) is a subset of a single step's term-reference identities — matching is per step, not against the union across steps. A step can also cover an activity explicitly via the `activity=` pin, regardless of its narration or its term count. |
 | **Kind inference** | The post-collection pass (`infer_glossary_kinds`) that assigns each undeclared term a kind from the *slot* positions it occupies across all story activities; declared kinds are verified against observed positions instead. A term used in incompatible slots (or conflicting with its declared kind) raises. A term never referenced by any activity stays *kindless*. |
 | **Kindless** | A term with `kind=None` — left unset when *kind inference* finds no story *slot* to infer from (a term used only in t-string steps, never in an activity). Shown in the report's *Uncategorized* bucket. |
 | **Undefined** | A term with `definition is None`; surfaced by a badge and filter in the Glossary view. Orthogonal to *kindless*. |