pytest-given 0.4.1__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. {pytest_given-0.4.1 → pytest_given-0.5.0}/AGENTS.md +29 -27
  2. {pytest_given-0.4.1 → pytest_given-0.5.0}/CHANGELOG.md +41 -1
  3. {pytest_given-0.4.1 → pytest_given-0.5.0}/GLOSSARY.md +38 -30
  4. {pytest_given-0.4.1 → pytest_given-0.5.0}/PKG-INFO +8 -1
  5. {pytest_given-0.4.1 → pytest_given-0.5.0}/README.md +5 -0
  6. {pytest_given-0.4.1 → pytest_given-0.5.0}/docs/site/configuration/narration-lint.md +8 -5
  7. {pytest_given-0.4.1 → pytest_given-0.5.0}/noxfile.py +150 -47
  8. {pytest_given-0.4.1 → pytest_given-0.5.0}/pyproject.toml +7 -3
  9. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +54 -0
  10. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +59 -0
  11. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +85 -0
  12. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md +21 -0
  13. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/references/parameter-tables.md +12 -0
  14. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +91 -0
  15. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +75 -0
  16. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-citing/SKILL.md +55 -0
  17. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-citing/references/repair.md +11 -0
  18. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +40 -0
  19. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +122 -0
  20. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +95 -0
  21. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/citations.md +10 -0
  22. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +28 -0
  23. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/hygiene.md +9 -0
  24. pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +36 -0
  25. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/collector.py +11 -11
  26. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/file_glossary.py +2 -2
  27. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/glossary.py +44 -6
  28. pytest_given-0.5.0/src/pytest_given/capture/markdown_glossary.py +121 -0
  29. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/scenario.py +14 -14
  30. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/story.py +5 -5
  31. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/template.py +59 -21
  32. pytest_given-0.5.0/src/pytest_given/citations/__init__.py +14 -0
  33. pytest_given-0.5.0/src/pytest_given/citations/check.py +684 -0
  34. pytest_given-0.5.0/src/pytest_given/citations/markdown_links.py +283 -0
  35. pytest_given-0.5.0/src/pytest_given/citations/narrated.py +342 -0
  36. pytest_given-0.5.0/src/pytest_given/citations/targets.py +148 -0
  37. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/cli/__init__.py +2 -0
  38. pytest_given-0.5.0/src/pytest_given/cli/citations.py +138 -0
  39. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/cli/report.py +35 -27
  40. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/checks.py +5 -2
  41. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/columns.py +6 -2
  42. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/context.py +1 -1
  43. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/group.py +8 -17
  44. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/percase.py +17 -10
  45. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/templatize.py +14 -12
  46. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/__init__.py +2 -2
  47. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/ast_rules.py +126 -31
  48. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/base.py +8 -6
  49. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/config.py +11 -9
  50. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/runner.py +2 -2
  51. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/runtime_rules.py +14 -14
  52. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/lint/summary.py +8 -10
  53. pytest_given-0.5.0/src/pytest_given/markdown/__init__.py +62 -0
  54. pytest_given-0.5.0/src/pytest_given/markdown/blocks.py +333 -0
  55. pytest_given-0.5.0/src/pytest_given/markdown/plain_text.py +68 -0
  56. pytest_given-0.5.0/src/pytest_given/markdown/spans.py +119 -0
  57. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/__init__.py +31 -6
  58. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/narration.py +68 -3
  59. pytest_given-0.5.0/src/pytest_given/model/report_url.py +43 -0
  60. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/runtime.py +3 -1
  61. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/schema.py +50 -11
  62. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/serde.py +45 -2
  63. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/text.py +22 -15
  64. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/__init__.py +2 -1
  65. pytest_given-0.5.0/src/pytest_given/plugin/case_ids.py +99 -0
  66. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/collection.py +23 -4
  67. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/fixtures.py +16 -15
  68. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/options.py +66 -4
  69. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/runtest.py +5 -2
  70. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/session.py +11 -6
  71. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/plugin/state.py +5 -3
  72. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/__init__.py +22 -0
  73. pytest_given-0.5.0/src/pytest_given/report/citation_index.py +237 -0
  74. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/coverage.py +1 -1
  75. pytest_given-0.5.0/src/pytest_given/report/function_source.py +90 -0
  76. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/glossary_view.py +38 -25
  77. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/html_renderer.py +104 -27
  78. pytest_given-0.5.0/src/pytest_given/report/inline_markdown.py +54 -0
  79. pytest_given-0.5.0/src/pytest_given/report/link_text.py +38 -0
  80. pytest_given-0.5.0/src/pytest_given/report/markdown_writer.py +105 -0
  81. pytest_given-0.5.0/src/pytest_given/report/md_renderer.py +379 -0
  82. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/sinks.py +22 -6
  83. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/slugs.py +11 -10
  84. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/story_view.py +16 -8
  85. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/_macros.html.j2 +40 -8
  86. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/app.js +248 -50
  87. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/report.html.j2 +70 -14
  88. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/styles.css +165 -11
  89. pytest_given-0.5.0/src/pytest_given/report/text.py +33 -0
  90. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/integration/test_cli.py +66 -3
  91. pytest_given-0.5.0/tests/integration/test_cli_citations.py +435 -0
  92. pytest_given-0.5.0/tests/integration/test_lazy_imports.py +25 -0
  93. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/integration/test_plugin.py +537 -180
  94. pytest_given-0.5.0/tests/integration/test_plugin_file_glossary.py +60 -0
  95. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/integration/test_plugin_lint.py +75 -56
  96. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/ubiquitous_language.py +8 -5
  97. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_collector.py +80 -88
  98. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_file_glossary.py +53 -51
  99. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_glossary.py +93 -70
  100. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_kind_inference.py +35 -36
  101. pytest_given-0.5.0/tests/unit/capture/test_markdown_glossary.py +265 -0
  102. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_step_descriptor.py +41 -38
  103. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_story.py +76 -82
  104. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_template.py +80 -24
  105. pytest_given-0.5.0/tests/unit/citation_reports.py +78 -0
  106. pytest_given-0.5.0/tests/unit/citations/fixtures/citation-forms.md +32 -0
  107. pytest_given-0.5.0/tests/unit/citations/test_check.py +1552 -0
  108. pytest_given-0.5.0/tests/unit/citations/test_markdown_links.py +316 -0
  109. pytest_given-0.5.0/tests/unit/citations/test_markdown_links_oracle.py +100 -0
  110. pytest_given-0.5.0/tests/unit/citations/test_narrated.py +290 -0
  111. pytest_given-0.5.0/tests/unit/citations/test_targets.py +130 -0
  112. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/lint/test_ast_rules.py +225 -31
  113. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/lint/test_config.py +5 -7
  114. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/lint/test_runtime_rules.py +26 -27
  115. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/lint/test_summary.py +7 -3
  116. pytest_given-0.5.0/tests/unit/markdown/test_blocks.py +168 -0
  117. pytest_given-0.5.0/tests/unit/markdown/test_plain_text.py +29 -0
  118. pytest_given-0.5.0/tests/unit/markdown/test_spans.py +134 -0
  119. pytest_given-0.5.0/tests/unit/model/__init__.py +0 -0
  120. pytest_given-0.5.0/tests/unit/model/test_narration.py +120 -0
  121. pytest_given-0.5.0/tests/unit/model/test_report_url.py +38 -0
  122. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/model/test_schema.py +47 -4
  123. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/model/test_serde.py +100 -3
  124. pytest_given-0.5.0/tests/unit/model/test_text.py +60 -0
  125. pytest_given-0.5.0/tests/unit/report/__init__.py +0 -0
  126. pytest_given-0.5.0/tests/unit/report/test_citation_index.py +288 -0
  127. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_coverage.py +104 -97
  128. pytest_given-0.5.0/tests/unit/report/test_function_source.py +124 -0
  129. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_glossary_view.py +111 -38
  130. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_html_renderer.py +294 -112
  131. pytest_given-0.5.0/tests/unit/report/test_inline_markdown.py +130 -0
  132. pytest_given-0.5.0/tests/unit/report/test_link_text.py +83 -0
  133. pytest_given-0.5.0/tests/unit/report/test_markdown_writer.py +210 -0
  134. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_md_renderer.py +633 -116
  135. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_sinks.py +40 -23
  136. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_slugs.py +10 -2
  137. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_source_link.py +3 -6
  138. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_story_view.py +14 -20
  139. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/test_grouping.py +212 -164
  140. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/test_percase.py +55 -21
  141. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/test_plugin.py +218 -2
  142. pytest_given-0.5.0/tests/unit/test_project_glossary.py +38 -0
  143. pytest_given-0.5.0/tests/unit/test_skills_data.py +115 -0
  144. pytest_given-0.5.0/uv.lock +1278 -0
  145. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +0 -52
  146. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +0 -59
  147. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/domain-storytelling.md +0 -35
  148. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +0 -82
  149. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +0 -105
  150. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +0 -76
  151. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +0 -41
  152. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +0 -117
  153. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +0 -71
  154. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/pairs.md +0 -65
  155. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +0 -29
  156. pytest_given-0.4.1/src/pytest_given/capture/markdown_glossary.py +0 -175
  157. pytest_given-0.4.1/src/pytest_given/report/inline_markdown.py +0 -51
  158. pytest_given-0.4.1/src/pytest_given/report/md_renderer.py +0 -289
  159. pytest_given-0.4.1/src/pytest_given/report/text.py +0 -24
  160. pytest_given-0.4.1/tests/integration/test_plugin_file_glossary.py +0 -42
  161. pytest_given-0.4.1/tests/unit/capture/test_markdown_glossary.py +0 -297
  162. pytest_given-0.4.1/tests/unit/model/test_narration.py +0 -15
  163. pytest_given-0.4.1/tests/unit/model/test_text.py +0 -22
  164. pytest_given-0.4.1/tests/unit/report/test_inline_markdown.py +0 -39
  165. pytest_given-0.4.1/tests/unit/test_skills_data.py +0 -67
  166. pytest_given-0.4.1/tests/unit/test_skills_scripts.py +0 -100
  167. pytest_given-0.4.1/uv.lock +0 -1206
  168. {pytest_given-0.4.1 → pytest_given-0.5.0}/.gitignore +0 -0
  169. {pytest_given-0.4.1 → pytest_given-0.5.0}/LICENSE.md +0 -0
  170. {pytest_given-0.4.1 → pytest_given-0.5.0}/THIRD-PARTY-LICENSES +0 -0
  171. {pytest_given-0.4.1 → pytest_given-0.5.0}/conftest.py +0 -0
  172. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/__init__.py +0 -0
  173. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/__init__.py +0 -0
  174. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/discovery.py +0 -0
  175. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/kind_inference.py +0 -0
  176. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/process_state.py +0 -0
  177. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/source.py +0 -0
  178. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/steps.py +0 -0
  179. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/capture/traceback.py +0 -0
  180. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/cli/skills.py +0 -0
  181. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/__init__.py +0 -0
  182. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/grouping/attachments.py +0 -0
  183. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/errors.py +0 -0
  184. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/model/steps.py +0 -0
  185. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/py.typed +0 -0
  186. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/palette.py +0 -0
  187. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/source_link.py +0 -0
  188. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/alpine.min.js +0 -0
  189. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/fonts/source-code-pro-latin-wght-normal.woff2 +0 -0
  190. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/fonts/source-sans-3-latin-wght-normal.woff2 +0 -0
  191. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/templates/logo.svg +0 -0
  192. {pytest_given-0.4.1 → pytest_given-0.5.0}/src/pytest_given/report/theme.py +0 -0
  193. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/__init__.py +0 -0
  194. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/conftest.py +0 -0
  195. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/integration/__init__.py +0 -0
  196. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/integration/test_plugin_session_isolation.py +0 -0
  197. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/integration/test_skills_cli.py +0 -0
  198. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/__init__.py +0 -0
  199. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/__init__.py +0 -0
  200. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_discovery.py +0 -0
  201. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_rootdir_isolation.py +0 -0
  202. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_source.py +0 -0
  203. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/capture/test_traceback_parser.py +0 -0
  204. {pytest_given-0.4.1/tests/unit/lint → pytest_given-0.5.0/tests/unit/citations}/__init__.py +0 -0
  205. {pytest_given-0.4.1/tests/unit/model → pytest_given-0.5.0/tests/unit/lint}/__init__.py +0 -0
  206. {pytest_given-0.4.1/tests/unit/report → pytest_given-0.5.0/tests/unit/markdown}/__init__.py +0 -0
  207. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/model/test_errors.py +0 -0
  208. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/model/test_steps.py +0 -0
  209. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_palette.py +0 -0
  210. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/report/test_theme.py +0 -0
  211. {pytest_given-0.4.1 → pytest_given-0.5.0}/tests/unit/test_plugin_traceback.py +0 -0
@@ -16,21 +16,23 @@ uv sync --group dev
16
16
 
17
17
  ## Quality gates
18
18
 
19
- `uv run nox` runs the default gate — `format`, `lint`, `mypy`, `test`, `coverage` (a 100% target), `audit` (a `pip-audit` of the locked dependencies). **Run it (or at minimum `uv run nox -s format lint mypy test`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
19
+ `uv run nox` runs the default gate — `format`, `lint`, `mypy`, `test`, `coverage` (a 100% target), `citations` (the documents' citations held to the committed reports), `audit` (a `pip-audit` of the locked dependencies). **Run it (or at minimum `uv run nox -s format lint mypy test`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
20
20
 
21
- - `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.
21
+ - `uv run nox -s examples` regenerates the example reports under `examples/`. Run after changes to the renderer, templates, plugin output schema, or any example test file, and commit the updated outputs.
22
22
  - `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 after renderer or template changes (its HTML is one of the site's example reports), and commit the updated outputs.
23
23
  - **Only commit a regenerated report when its *content* actually changed.**
24
24
  - 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.
25
- - **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.
26
- - Regenerate only the reports a change can affect — `examples` narrates `examples/**`, `self_report` narrates `tests/**`, and a renderer or template change affects all of them. A shifted line number in a decorated backend test is therefore a real self-report change worth committing, even when no example changed.
27
- - Both regeneration sessions run the narration lint (`--given-lint`; see [Narration lint](docs/site/configuration/narration-lint.md) and the [design spec](docs/specs/2026-07-05-narration-lint-design.md)). `self_report` fails on any lint error — a real gate, keep the backend suite lint-clean. `examples` tolerates exit 1 for its intentional failures, which masks the lint exit code, so read the printed "narration lint" summary there. A step the lint mis-flags goes on the `given_lint_ignore` list (stale entries fail the run); the rule catalog and ignore mechanics are in the [authoring skill](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) under "Mechanical counterparts", and the honest-two-phase test an ignored `missing-phase` has to pass under "Phase structure".
25
+ - **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, nor do anchor lines: `given_md_lines = false`). A test that only moved is noise; its SHA-pinned source link still points right.
26
+ - Regenerate only the reports a change can affect — `examples` narrates `examples/**`, `self_report` narrates `tests/**`, and a renderer or template change affects all of them.
27
+ - `uv run nox -s reports_current` is CI's check that a change regenerated what it should: it runs both regeneration sessions and fails if any tracked `.md` changed — a report's Markdown or a document whose citations moved. Locally it leaves the regenerated files behind, to commit or `git checkout`.
28
+ - Both regeneration sessions also run `pytest-given citations update` — `self_report` over `docs/specs/`, both over `docs/site/` — so commit the documents they change with the report.
29
+ - Both regeneration sessions run the narration lint (`--given-lint`; see [Narration lint](docs/site/configuration/narration-lint.md) and the [design spec](docs/specs/2026-07-05-narration-lint-design.md)). `self_report` fails on any lint error — a real gate, keep the backend suite lint-clean. `examples` tolerates exit 1 for its intentional failures, which masks the lint exit code, so read the printed "narration lint" summary there. A step the lint mis-flags goes on the `given_lint_ignore` list (stale entries fail the run); the rule catalog, ignore mechanics, and when an ignored `missing-phase` is justified are in the authoring skill's [lint.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md).
28
30
  - `uv run nox -s benchmark` generates the large-scenarios suite and renders its JSON + HTML into `benchmarks/` (outputs gitignored). Run it when a change could move report-generation cost; `benchmarks/bench.py` does size sweeps and cProfile runs directly.
29
- - `uv run nox -s compat` runs the suite on Python 3.14 and 3.15, each against pytest 9.0.x (the dependency floor) and the newest pytest. The default gate tests only the locked pytest on 3.14, so this is the only check of the floor and of 3.15. The manually dispatched [Compat workflow](.github/workflows/compat.yml) runs it on Linux and Windows before every release (see [docs/releasing.md](docs/releasing.md)).
30
- - `uv run nox -s build` builds the wheel + sdist and verifies them as a consumer would — `py.typed`, templates and bundled skills present, a real scenario run from a throwaway install, and [library-skills](https://library-skills.io) discovery of every bundled skill. The in-repo suite imports from `src/`, so this session is the only thing that catches a packaging regression. CI and the release workflow both run it.
31
+ - `uv run nox -s compat` runs the suite against the oldest supported pytest and markdown-it-py and the newest, on every supported Python — raising either floor in `pyproject.toml` moves its pin there too. The default gate tests only the locked versions on one Python, so this is the only check of the rest. Before a release, the [Compat workflow](.github/workflows/compat.yml) runs it on GitHub's Linux and Windows runners.
32
+ - `uv run nox -s build` builds the wheel + sdist and verifies them as a consumer would. The in-repo suite imports from `src/`, so this session is the only thing that catches a packaging regression. CI and the release workflow both run it.
31
33
  - `uv run nox -s docs_build` builds the documentation site under `site/` with `zensical build --strict`; run it after changing anything under `docs/site/` (a broken cross-page link fails it) and preview with `uv run --group docs zensical serve`. `docs_deploy` is the CI-only counterpart that publishes with mike — see [docs/releasing.md](docs/releasing.md#documentation-site).
32
- - Zensical builds every file in `docs/site/` and cannot exclude any, so single-sourced files get in by copy or include: the build copies the four example reports, the full-size diagram, and the report package's upright fonts and logo into gitignored spots there; `CHANGELOG.md` (between its `site` markers) and the Home-page diagram (`docs/site/assets/pytest-given-diagram.svg`, inlined so page CSS can theme it) are `pymdownx.snippets` includes.
33
- - `docs/pytest-given-diagram.svg`, the README's diagram and the Home page's full-size view, is derived with the font embedded and the colour tokens resolved: after editing the source SVG or its tokens, run `uv run nox -s diagram` and commit the result.
34
+ - Zensical builds every file in `docs/site/` and cannot exclude any, so a file single-sourced elsewhere gets in by a copy the build stages into a gitignored spot (listed in `_build_docs`) or by a `pymdownx.snippets` include — never by a committed second copy.
35
+ - `docs/pytest-given-diagram.svg`, the README's diagram and the Home page's full-size view, is derived with the font embedded and the colour tokens resolved: after editing the source SVG (`docs/site/assets/pytest-given-diagram.svg`) or its tokens, run `uv run nox -s diagram` and commit the result.
34
36
  - The site self-hosts its fonts so a visitor's browser contacts no third party — keep `font = false` in `zensical.toml` and don't `@import` a font CDN. Only the italics live in `docs/site/assets/fonts/` (latin subsets from Fontsource); a new face gets its `.woff2` there and its copyright line in that folder's `LICENSES.txt`.
35
37
 
36
38
  ## Releasing
@@ -39,37 +41,36 @@ Releases go to PyPI via a manually dispatched [Release workflow](.github/workflo
39
41
 
40
42
  ## Architecture
41
43
 
42
- `src/pytest_given/` is five library subpackages plus two entry points, with a
44
+ `src/pytest_given/` is seven library subpackages plus two entry points, with a
43
45
  strict dependency direction (convention, not lint-enforced):
44
46
 
45
47
  ```
46
- model/ the leaf — schema, serde, errors, shared text rules
48
+ markdown/ the leaf — reading Markdown: blocks, tables, inline spans
49
+ model/ schema, serde, errors, shared text rules
47
50
  capture/ lint/ report/ each on model/ only, never on each other
48
51
  grouping/ on model/ + capture/
49
- plugin/ cli/ the entry points; may import all five, and hold
50
- nothing the five could
52
+ citations/ on model/ + report/
53
+ plugin/ cli/ the entry points; may import all seven, and hold
54
+ nothing the seven could
51
55
  ```
52
56
 
57
+ Every package may import `markdown/`, which imports none of them.
58
+
53
59
  What no filename tells you:
54
60
 
55
61
  - `grouping/` — the parametrize pass: a scenario's cases collapsed into one
56
62
  narrated tree plus a parameter table, refusing the authoring forms that would
57
63
  make that tree lie. Runs at session finish *before* the sinks are written, so
58
64
  a bare `pytest` failing on one is the point, not a side effect.
59
- - `plugin/__init__.py` is the hook surface pluggy registers — the `pytest11`
60
- entry point is the package, and pluggy scans a module's attributes for
61
- `pytest_*` names, so the re-exports there *are* the registration.
62
65
  - `capture/` imports pytest nowhere, so all of it is unit-testable without a
63
66
  session; a stray step warns with `model.PytestGivenWarning`, not pytest's.
64
- - `Glossary` exists twice on purpose: `model/schema.py` holds the storage the
65
- report carries and serde rebuilds, and `capture/glossary.py` subclasses it
66
- with the registration API, which needs a caller source location that the leaf
67
- may not reach for. `pytest_given.Glossary` is the subclass; everything
68
- internal annotates the base. `LookupGlossary` sits between them and owns the
69
- `g['Guest']` read-back both user-facing glossaries share.
67
+ - `citations/` reads and edits the user's Markdown documents; what a citation
68
+ should say is `report`'s `CitationIndex`, since the HTML's copy buttons write
69
+ the same lines.
70
70
  - Each package exposes the *whole* job, not its parts: `report.emit_sinks`
71
71
  (render → write → discard-on-failure, so a failure leaves no half-written
72
- report) and `lint.run_lint`. Both entry points reach the sinks through
72
+ report), `lint.run_lint` and `citations.check_citations` (every document
73
+ read before any is written). Both entry points reach the sinks through
73
74
  `emit_sinks`, which is what keeps `pytest-given report` behaving like the
74
75
  plugin; the lint is the plugin's alone, since the CLI re-renders a report
75
76
  rather than running a suite.
@@ -90,7 +91,6 @@ Any change to `report/templates/` (Jinja, CSS, `app.js`) or the `narration` filt
90
91
  - **No TDD for frontend changes**: apply the change, regenerate `examples/`, drive it in Playwright, capture the result.
91
92
  - 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.
92
93
  - Desktop only — assume a minimum viewport width of ~900px.
93
- - Traceback display and header metadata formatting are known limitations, not current priorities.
94
94
  - Never save Playwright screenshots into the project directory — use the session scratchpad or omit the `filename` parameter.
95
95
 
96
96
  **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.
@@ -99,7 +99,7 @@ Any change to `report/templates/` (Jinja, CSS, `app.js`) or the `narration` filt
99
99
 
100
100
  The narration rules live in the **`pytest-given-authoring` skill**, whose canonical source is [src/pytest_given/.agents/skills/](src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md) — every link in this document points there. The copy under `.claude/skills/` is a mirror: after editing the canonical copy, regenerate it with `uv run pytest-given skills install` and commit both (a sync test fails otherwise).
101
101
 
102
- **The skill is documentation with the same sync duty as the site** — downstream agents read it instead of the site, version-matched from the wheel. A change to the public API surface or its rules updates the site page under `docs/site/` *and* [references/api.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md); a change to narration/lint semantics updates [references/scenarios.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) and friends. No check catches prose drift between the site and the skill, so ask "does the skill need this too?" on every user-facing change; only the `python` blocks are covered — `tests/unit/test_skills_scripts.py` runs each against a report built from the model. The reviewing skill restates authoring rules as rubrics, so they share the same duty: its layer 2 mirrors `scenarios.md` ("Keeping it truthful", "Expected raises", "Vocabulary and tags"), and its layer 4 mirrors `glossaries.md` ("Keeping the glossary honest") and `stories.md` — change one, change both.
102
+ **The skill is documentation with the same sync duty as the site** — downstream agents read it instead of the site, version-matched from the wheel. A change to the public API surface or its rules updates the site page under `docs/site/` *and* [references/api.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md); a change to narration/lint semantics updates [references/scenarios.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) and friends. No check catches prose drift between the site and the skill, so ask "does the skill need this too?" on every user-facing change. The reviewing skill restates the authoring skill's rules as rubrics, so they share the same duty — change one, change both.
103
103
 
104
104
  Narration drifts like any other prose — the lint catches several ways step text and body can part company, not all of them — which is why [Quality gates](#quality-gates) has you read the regenerated `.md` rather than trust the text.
105
105
 
@@ -114,9 +114,11 @@ What is specific to this repo's self-report:
114
114
 
115
115
  - 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/.agents/skills/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.
116
116
  - **Docstrings only for what the code cannot say** — a non-obvious invariant, a constraint that makes the shape necessary, a trap for the next reader — and a line or two at most. No signature restatement, no implementation narration, no `X is the only caller of Y` cross-references (they rot fastest; the reader can grep). Prefer a precise name to a sentence explaining a vague one. When you change a module, delete the sentences that have stopped being true rather than repairing them.
117
+ - Internal code annotates a glossary as the base `model.Glossary`, never `pytest_given.Glossary` (the `capture` subclass users register terms on): a report rebuilt from JSON and a `FileGlossary` both carry no such subclass.
117
118
  - Avoid `Any` — use precise types, generics, `TYPE_CHECKING` imports, or `ContextVar[T]` over untyped `threading.local`.
118
119
  - 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.
119
- - Only module-level imports — no inline/function-level imports.
120
+ - Every package `src/` imports is a declared dependency in `pyproject.toml`, even one another dependency already brings in.
121
+ - Only module-level imports — no inline/function-level imports. A third-party package only some sessions or commands use goes in the importing module's `__lazy_modules__` (Python 3.15 defers it to first use; `tests/integration/test_lazy_imports.py` holds the entry points to it).
120
122
  - **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).
121
123
  - 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.
122
124
  - 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).
@@ -129,4 +131,4 @@ What is specific to this repo's self-report:
129
131
  - **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.
130
132
  - **One sentence per entry**, written for someone upgrading: name the symbol, flag, or surface and say what changed — no rationale, measurements, or before/after detail. Only a breaking change earns more: the migration it needs. Visual and interaction polish gets one collective bullet per release ("the sidebar and its chips are visually tidied"), never a bullet per restyled element; accessibility fixes stay on their own line. When in doubt, the shorter entry is the right one.
131
133
  - Plan files under `docs/superpowers/plans/` are gitignored scratch; spec files under `docs/specs/` are committed.
132
- - 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.
134
+ - New specs land under `docs/specs/proposed/`. When a spec's implementation lands — its citations all read ✅ — `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.
@@ -11,6 +11,45 @@ form `## [x.y.z] - YYYY-MM-DD`.
11
11
 
12
12
  <!-- --8<-- [start:site] -->
13
13
 
14
+ ## [0.5.0] - 2026-10-18
15
+
16
+ ### Added
17
+
18
+ - Markdown documents, such as design specs, can [cite](https://nwilbert.github.io/pytest-given/0.5/guide/citations/) scenarios, tags and stories as links into the published HTML report: `--given-report-url` or the `given_report_url` setting sets the report's URL and gives it buttons that copy a citation, `pytest-given citations check` and `pytest-given citations update` keep a document's citations in line with a JSON report, a scenario's narration in a `<details markdown="1">` block included, `citations check --list` prints every report link with its findings, narrowed by `--covering` to the links that [cite a scenario](https://nwilbert.github.io/pytest-given/0.5/guide/citations/#finding-the-citations-of-a-scenario), and the bundled `pytest-given-citing` skill writes citations and repairs the ones `citations update` cannot.
19
+ - When a link into the HTML report points at a scenario, tag or other filter the report no longer has, the report warns that the link is out of date, names what is missing, and ignores it.
20
+ - A [term ref](https://nwilbert.github.io/pytest-given/0.5/guide/glossary/#term-refs) can show a noun's plural or a verb's -s form with `.s`: `room.s` reads *Rooms*, `room.l.s` reads *rooms*, and `room('suite').s` reads *suites*.
21
+ - Every `@scenario` test carries the registered `pytest_given` marker, so `pytest -m pytest_given` [runs the scenarios alone](https://nwilbert.github.io/pytest-given/0.5/configuration/pytest-options/#selecting-scenarios), for example to measure their code coverage.
22
+ - `pytest-given report --report-url` re-renders a saved report for a URL other than the one stored in it.
23
+ - The `given_md_lines = false` setting, or `--no-given-md-lines` (`--no-lines` on `pytest-given report`), leaves the line number out of each Markdown scenario anchor.
24
+ - `--given-md-source` ends each scenario in the Markdown report with its test function, under its line numbers.
25
+ - The [narration lint](https://nwilbert.github.io/pytest-given/0.5/configuration/narration-lint/#rules)'s `conditional-check` rule (default `warn`) flags a `then` whose checks all sit under an `if`, a loop, a `match` or an `except`.
26
+ - Scenario titles and step text render `**bold**`, `*italic*` and `` `code` `` in the HTML report.
27
+ - A [parameter table](https://nwilbert.github.io/pytest-given/0.5/guide/parametrized/#grouping) starts with a `case ID` column when any case ID is custom, and each case in the JSON report's `parameters.cases[]` carries its node ID as `id` and a `custom_id` flag.
28
+ - A Tags sidebar row in the HTML report has a copy button for the tag's link and citation.
29
+
30
+ ### Changed
31
+
32
+ - The Markdown report indents nested steps and attachments by four spaces.
33
+ - **Breaking.** `@scenario`'s first parameter is now `title`: replace `@scenario(name=...)` with `@scenario(title=...)`; a positional title is unaffected.
34
+ - **Breaking.** `FileGlossary`'s `description_column` is now `definition_column`, the word the rest of the glossary API uses: rename the keyword.
35
+ - **Breaking.** A handle's `.low` form is now `.l`, and lowercases only capitalized words, so an acronym keeps its case (`LLM Call` reads *LLM call*): replace `.low` with `.l`.
36
+ - **Breaking.** Glossary definitions render emphasis as CommonMark does, so `__bold__` no longer renders and `FileGlossary` no longer unwraps it in term and kind cells: write `**bold**`.
37
+ - **Breaking.** A title or step whose code span, bold or italics holds a value, placeholder or term ref raises `PytestGivenError`, and so do asterisks meant literally around one, as in `t'**/{d}/**'`: keep the span within the text beside it, and put a literal `*` in a code span of its own.
38
+ - The Glossary tab lists a term's instances and other wordings under one "Other forms" label, leaving out a term ref that reads as its S-form.
39
+ - The Markdown report and citations escape Markdown in all text except a title's or step's own formatting, and show a newline in a title or step as a space.
40
+ - A per-case scenario title highlights its case ID as a value, and the JSON report records it as a value part.
41
+ - The HTML report's top bar, term ref underlines, copy buttons and sidebar are visually tidied.
42
+ - The bundled skills are reworded in plainer language and load their lint catalog, parameter-table guidance and audits from reference files only when a task needs them.
43
+ - The bundled `pytest-given-authoring` skill covers scenario titles, parameter-table outcomes, custom case IDs and glossary definitions, and `pytest-given-reviewing` checks for each of them and starts its completeness audit from what the project promises.
44
+ - A `--given-lint` run that finds nothing prints `pytest-given: narration lint (no findings)`.
45
+ - pytest-given now depends on markdown-it-py.
46
+ - `FileGlossary` reads the tables a GFM renderer shows, so it reads a table in a blockquote or list, skips one in an indented code or HTML block, and reads a cell missing from a row as empty instead of raising.
47
+
48
+ ### Fixed
49
+
50
+ - Notes below a parameter table in the Markdown report that would share a key add their row number.
51
+ - The narration lint checks a test file with an encoding declaration, such as `# -*- coding: latin-1 -*-`, instead of skipping it.
52
+
14
53
  ## [0.4.1] - 2026-10-04
15
54
 
16
55
  ### Fixed
@@ -394,7 +433,8 @@ First public release.
394
433
  - Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
395
434
  the wheel and version-matched to the plugin.
396
435
 
397
- [Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...HEAD
436
+ [Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.5.0...HEAD
437
+ [0.5.0]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...v0.5.0
398
438
  [0.4.1]: https://github.com/nwilbert/pytest-given/compare/v0.4.0...v0.4.1
399
439
  [0.4.0]: https://github.com/nwilbert/pytest-given/compare/v0.3.0...v0.4.0
400
440
  [0.3.0]: https://github.com/nwilbert/pytest-given/compare/v0.2.0...v0.3.0
@@ -11,11 +11,12 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
11
11
  | Term | Meaning |
12
12
  |---|---|
13
13
  | **Scenario** | A test function decorated with `@scenario(...)`. Not every pytest test is a scenario — undecorated tests are tolerated but not collected. |
14
- | **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. |
15
- | **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. |
14
+ | **Scenario title** | The text `@scenario` takes first: the statement of the rule a *Scenario* demonstrates, shown as its heading in the report. A plain string, a t-string of glossary handles, or a `Template` filled per *Case*; recorded as the scenario's *Narration*. Not the test function's name, which the node ID carries. |
15
+ | **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*. |
16
+ | **Narration** | The human-readable text on a step or scenario title. 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. |
16
17
  | **Phase** | The category of a step: `given`, `when`, or `then`. A step has exactly one phase. |
17
18
  | **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. |
18
- | **Tag** | Free-form string label attached via `@scenario(name, tags=[...])`. Used by the report's filter UI, where a `/` nests it (`ticket/ABC-123` under `ticket`) and selecting a prefix filters to every tag beneath it. |
19
+ | **Tag** | Free-form string label attached via `@scenario(title, tags=[...])`. A `/` nests it: `ticket/ABC-123` sits under `ticket`. |
19
20
  | **Attachment** | A labeled blob (text or JSON) bound to the currently-active step via `attach(label, content)`. |
20
21
 
21
22
  ## Parametrization
@@ -23,8 +24,9 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
23
24
  | Term | Meaning |
24
25
  |---|---|
25
26
  | **Parametrized scenario** | A `@scenario`-decorated test that also carries `@pytest.mark.parametrize(...)`. Produces multiple scenario records during a run; pytest-given groups them. |
26
- | **Case** | One row of a parametrized scenario — a single tuple of parameter values, its status, and any error. |
27
- | **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. |
27
+ | **Case** | One row of a parametrized scenario — its node ID, a single tuple of parameter values, its status, and any error. |
28
+ | **Case ID** | A *Case*'s pytest ID: its *Node ID*'s parametrize tail without the brackets (`touching-edges`), as the terminal prints it. *Custom* when it is more than its values' generated parts, as from `pytest.param(..., id=...)` or `ids=`. |
29
+ | **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). |
28
30
  | **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. |
29
31
  | **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. |
30
32
 
@@ -33,18 +35,19 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
33
35
  | Term | Meaning |
34
36
  |---|---|
35
37
  | **Step fixture** | A pytest fixture whose function is wrapped with `@given(text)`. Only `@given` is allowed on fixtures; `@when` / `@then` are rejected. |
36
- | **Plain fixture** | A pytest fixture without a pytest-given decorator. It produces no step in the report unless an `Annotated[..., given(...)]` label on the test's parameter narrates it. |
37
- | **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. |
38
+ | **Plain fixture** | A pytest fixture without a pytest-given decorator. It produces no step in the report unless a *Given annotation* on the test's parameter narrates it. |
39
+ | **Given annotation** | A `given(...)` in a test parameter's `Annotated[...]` type: `def test(room: Annotated[int, given('a room')])`. On a parametrize value or a *Plain fixture* it adds a childless `given` step; on a *Step fixture* it replaces the fixture's root label and its pins. Only `given` is allowed, and a `Template` in it may only hold a bare parametrize column. |
40
+ | **Fixture recording** | A captured subtree of steps + attachments produced while a step fixture is being set up. A generator fixture's teardown records nothing — it refuses steps and attachments. |
38
41
  | **Graft** | Attaching a fixture recording into the active scenario's step tree at the moment its host test starts. |
39
42
 
40
43
  ## Collector state
41
44
 
42
45
  | Term | Meaning |
43
46
  |---|---|
44
- | **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. |
45
- | **Active scenario** | The scenario currently being recorded into; tracked by node ID. |
46
- | **Node ID** | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). Used as a key throughout the collector. |
47
- | **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. |
47
+ | **Collector** | The per-session object accumulating scenarios, fixture recordings, and parameter info. |
48
+ | **Active scenario** | The scenario currently being recorded into. |
49
+ | **Node ID** | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). |
50
+ | **Step stack** | The chain of currently-open steps. A `with given(...)` pushes one, and leaving the block pops it. |
48
51
 
49
52
  ## Report
50
53
 
@@ -54,17 +57,21 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
54
57
  | **Renderer** | Converts a JSON report into a rendering — a self-contained HTML page or a Markdown document. |
55
58
  | **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. |
56
59
  | **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. |
57
- | **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. |
58
- | **Theme** | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). The `given_theme` config sets the default a report opens in; a viewer's own choice from the report's theme control, once made, wins over it in that browser. |
60
+ | **Source link** | A clickable file:line anchor on a scenario card, a story panel, or an expanded glossary term card. It points at a scenario's test function, or at the declaration of a *Story* or *Term*. |
61
+ | **Report link** | A Markdown link to a scenario, tag or story in the HTML *Report*: the report's URL with a `#scenario=<node ID>`, `#tag=<tag>` or `#view=stories&story=<story id>` fragment. Without a glyph it is a plain one, which claims only that its target exists. |
62
+ | **Citation** | A *Report link* led by its target's status glyph, citing a scenario, tag or story from a Markdown document: `✅ [title](<report URL>#scenario=…)`. A tag or story citation adds a summary after it, `(5 ✅ · 2 🔵)`. A target the *Report* lacks reads `❓`. |
63
+ | **Narrated citation** | A *Citation* of a scenario written as a `<details markdown="1">` block, the citation in its `<summary>` and the scenario's Markdown narration in its body. |
64
+ | **Citation finding** | One problem `pytest-given citations check` reports on one *Report link*: its kind (`stale`, `missing`, `failed`, `mistyped`, …), the document location and a message. |
65
+ | **Theme** | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). |
59
66
 
60
67
  ## Narration lint
61
68
 
62
69
  | Term | Meaning |
63
70
  |---|---|
64
- | **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. |
65
- | **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. |
66
- | **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. |
67
- | **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. |
71
+ | **Narration lint** | The `--given-lint` pass that checks recorded scenarios against the *Lint rule* catalog. It enforces the structural subset of the narration conventions — it cannot check whether a *Step*'s text is semantically true. |
72
+ | **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. |
73
+ | **Lint 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. |
74
+ | **Severity** | A *Lint rule*'s level — `off`, `warn` or `error`. Only `error` fails the run, `warn` reports in the terminal summary, and an `off` rule is not evaluated at all. |
68
75
 
69
76
  ## Domain Storytelling
70
77
 
@@ -74,28 +81,29 @@ Terms follow [Domain Storytelling](https://domainstorytelling.org/quick-start-gu
74
81
 
75
82
  | Term | Meaning |
76
83
  |---|---|
77
- | **Glossary** | The Ubiquitous-Language concept — the shared vocabulary a domain speaks in — and the class that realizes it: `Glossary()`, with `.actor(...)`, `.work_object(...)`, `.activity(...)` registration methods and `g('foo')` (declare-or-get a kindless term, optional `definition=`) / `g['foo']` (get-only, raises on unknown) accessor forms. |
78
- | **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 clause *slot* positions when no explicit `kind_column` is configured. |
84
+ | **Glossary** | The Ubiquitous-Language concept — the shared vocabulary a domain speaks in — and the class that realizes it in code: `Glossary()`, on which terms are registered. |
85
+ | **File glossary** | A glossary loaded from the GFM pipe tables of a Markdown file, via the `FileGlossary(path)` class. |
79
86
  | **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. |
80
- | **Term** | A registered glossary entry: an Actor, Work Object, Activity, 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). |
81
- | **Handle** | The Python object a glossary hands back for a *term* — `TermHandle`, the same type from every accessor (`g.actor(...)`, `g('foo')`, `g['Guest']`, a captured `guest = ...`). It is what steps, scenario titles and sentences interpolate, in one of three surface forms: **bare** (`room` — the canonical display), **`.low`** (`room.low` — lowercased), or **called** (`room('Deluxe Suite')` — an *instance* on an Actor or Work Object, an inflection on an *Activity*). Each form renders as a *term ref*. A story hands out a **sentence handle** the same way: `book_a_room['cancel']` by name or `book_a_room[3]` by number, which `pins=` takes. |
82
- | **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). Carries the actor kind color in the report. |
83
- | **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). Carries the work-object kind color in the report. |
84
- | **Activity** | A glossary term for what an actor does (e.g., *book*, *confirm*), which Domain Storytelling draws as an arrow labelled with a verb. Activities accept inflections: calling `book('books')` records *books* as a surface form of the canonical *book*. |
87
+ | **Term** | A registered glossary entry: an Actor, Work Object, Activity, or kindless term. Each carries an id (slug), a canonical name, a kind (`None` when kindless), and an optional definition. |
88
+ | **Handle** | The Python object a glossary hands back for a *term* — `TermHandle`, the same type from every accessor (`g.actor(...)`, `g('foo')`, `g['Guest']`, a captured `guest = ...`). It is what steps, scenario titles and sentences interpolate, in one of four surface forms: **bare** (`room` — the canonical display), **`.l`** (`room.l` — capitalized words lowercased, acronyms kept), **`.s`** (`room.s` — the *S-form*), or **called** (`room('Deluxe Suite')` — an *instance* on an Actor or Work Object, an inflection on an *Activity*). `.l` and `.s` also apply to a called form and chain (`room.l.s` reads *rooms*). Each form renders as a *term ref*. A story hands out a **sentence handle** the same way: `book_a_room['cancel']` by name or `book_a_room[3]` by number, which `pins=` takes. |
89
+ | **S-form** | A term's name with the regular English -s ending, from the `.s` handle form: the plural of an Actor or Work Object (*rooms*), the third person singular of an Activity (*books*). It adds -s to the last word, -es after s, x, z, ch or sh, and turns a consonant + y into -ies, but an acronym takes a plain -s (*APIs*); anything else, such as *people* or *checks in*, needs the called form. An S-form reference, in any case, is a reference to the term itself — not an *instance* or an *inflection*. |
90
+ | **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). |
91
+ | **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). |
92
+ | **Activity** | A glossary term for what an actor does (e.g., *book*, *confirm*), which Domain Storytelling draws as an arrow labelled with a verb. Activities accept inflections: calling `search('searches for')` records *searches for* as a surface form of the canonical *search*. |
85
93
  | **Term ref** | An occurrence of a term inside narration. Modeled as `NarrationTermRef` in step text and as `ClauseTermRef` inside a clause. |
86
- | **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. |
87
- | **Inflection** | A surface form of an Activity term other than its canonical name (e.g., *searches for* as an inflection of *search*). Reported under "Also used as:" in the Glossary. |
88
- | **Story** | A named flow modeled as a sequence of sentences. Constructed by `story('Title', [sentence(...), ...])`. Stories are first-class report tabs and the unit of coverage. |
94
+ | **Instance** | A named refinement of an Actor or Work Object (e.g., `guest('Alice')` is an instance of the *Guest* actor). |
95
+ | **Inflection** | A surface form of an Activity term other than its canonical name or *S-form* (e.g., *searches for* as an inflection of *search*). |
96
+ | **Story** | A named flow modeled as a sequence of sentences. Constructed by `story('Title', [sentence(...), ...])`. Stories are the unit of coverage. |
89
97
  | **Sentence** | What Domain Storytelling calls a sentence: an actor, an activity and its work objects, plus connective words. One row in a story, numbered by its position (1..N, never set by hand) and optionally named with `sentence(..., name='cancel')`, a name that stays put when rows are inserted. Constructed by `sentence(...)`. Usually one clause, built implicitly; several when the sentence has several arrows under one number. |
90
98
  | **Clause part** | The two-variant union making up a clause's prose (`ClausePart` = `ClauseTermRef` or `ClauseWord`): a reference to a glossary term, whose kind resolves via the glossary, or a bare clause 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. |
91
99
  | **Clause** | One linear walk through a sentence's arrows, a node/edge alternation starting actor → verb → noun, constructed by `clause(...)`. A sentence with several arrow chains under one number, such as an actor handing a work object to two recipients, takes one clause per chain. Domain Storytelling names no such unit. |
92
- | **Slot** | A position role in a clause, 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 clause validation and *kind inference*. |
100
+ | **Slot** | A position role in a clause, from its node/edge alternation: position 0 is the actor slot, odd positions are verb slots, and even positions ≥ 2 are noun slots. |
93
101
  | **Scenario↔sentence binding** | The link between a scenario (or step) and story sentences. `@scenario(stories=...)` names the stories a scenario is narration-matched against; a *pin* (`pins=` on `@scenario` or on `given`/`when`/`then`) binds sentences explicitly, in any story, whether `stories=` names it or not. |
94
102
  | **Pin** | What a *sentence handle* passed to `pins=` is recorded as, the way a term handle in narration is recorded as a *term ref*: a `Pin` naming a story and a sentence number. A pin binds explicitly and replaces narration matching — a step pin for that step, a scenario pin (`@scenario(pins=...)`) for every step of the scenario, which then covers its own pins plus its steps'. `pins=[]` pins nothing but still opts out of narration matching. A pin reaches under-anchored sentences too. |
95
103
  | **Coverage** | The "did this scenario touch that sentence" relation. Computed by the *A_refs ⊆ S* rule: a sentence is covered when the set of terms it references is a subset of the terms a single step references — matching is per step, not against the union across steps, and on terms, not surface forms: an *instance* or *inflection* counts as its term. A *pin* covers its sentences directly instead, regardless of narration or term count. |
96
104
  | **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 sentences; 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 sentence stays *kindless*. |
97
- | **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 a sentence). Shown in the report's *Uncategorized* bucket. |
98
- | **Undefined** | A term with `definition is None`; surfaced by a badge and filter in the Glossary view. Orthogonal to *kindless*. |
105
+ | **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 a sentence). |
106
+ | **Undefined** | A term with `definition is None`. Orthogonal to *kindless*. |
99
107
 
100
108
  ## Collaboration
101
109
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pytest-given
3
- Version: 0.4.1
3
+ Version: 0.5.0
4
4
  Summary: A pytest plugin that generates interactive HTML reports from Given/When/Then annotated tests.
5
5
  Project-URL: Homepage, https://github.com/nwilbert/pytest-given
6
6
  Project-URL: Repository, https://github.com/nwilbert/pytest-given
@@ -24,6 +24,8 @@ Classifier: Topic :: Software Development :: Testing
24
24
  Classifier: Typing :: Typed
25
25
  Requires-Python: >=3.14
26
26
  Requires-Dist: jinja2>=3.1
27
+ Requires-Dist: markdown-it-py>=3.0
28
+ Requires-Dist: markupsafe>=2.0
27
29
  Requires-Dist: pytest>=9.0
28
30
  Description-Content-Type: text/markdown
29
31
 
@@ -115,6 +117,10 @@ More and more tests aren't written by hand. A person describes a scenario, an AI
115
117
 
116
118
  pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/) defines the terms your team uses, and the report highlights them wherever a test mentions them. [Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/) adds the big picture: stories of how the domain works, with the report showing which scenarios cover each sentence of a story.
117
119
 
120
+ ### Documents that stay true
121
+
122
+ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run, and `pytest-given citations check` in CI fails when a cited scenario stops passing or disappears, so the document can't quietly claim what the code no longer does.
123
+
118
124
  ## Features
119
125
 
120
126
  - **[Step context managers](https://nwilbert.github.io/pytest-given/latest/guide/scenarios/)**: `with given(...)`, `when(...)`, `then(...)` blocks in plain pytest tests, nesting within a phase.
@@ -123,6 +129,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
123
129
  - **[Glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/)**: your domain's terms, declared in code or loaded from a `GLOSSARY.md`, rendered as highlighted term refs in the narration.
124
130
  - **[Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/)**: Domain Stories as sequences of sentences, and per-sentence coverage in the report.
125
131
  - **[Narration lint](https://nwilbert.github.io/pytest-given/latest/configuration/narration-lint/)**: structural checks that a step's text is honest about its body: empty steps, a `then` that checks nothing, a missing phase.
132
+ - **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and stories, led by their status and checked against the latest run.
126
133
  - **[Agent skills](https://nwilbert.github.io/pytest-given/latest/ai-agents/)**: bundled Agent Skills for authoring, navigating and reviewing narrated tests, installable with one command.
127
134
 
128
135
  The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
@@ -86,6 +86,10 @@ More and more tests aren't written by hand. A person describes a scenario, an AI
86
86
 
87
87
  pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/) defines the terms your team uses, and the report highlights them wherever a test mentions them. [Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/) adds the big picture: stories of how the domain works, with the report showing which scenarios cover each sentence of a story.
88
88
 
89
+ ### Documents that stay true
90
+
91
+ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run, and `pytest-given citations check` in CI fails when a cited scenario stops passing or disappears, so the document can't quietly claim what the code no longer does.
92
+
89
93
  ## Features
90
94
 
91
95
  - **[Step context managers](https://nwilbert.github.io/pytest-given/latest/guide/scenarios/)**: `with given(...)`, `when(...)`, `then(...)` blocks in plain pytest tests, nesting within a phase.
@@ -94,6 +98,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
94
98
  - **[Glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/)**: your domain's terms, declared in code or loaded from a `GLOSSARY.md`, rendered as highlighted term refs in the narration.
95
99
  - **[Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/)**: Domain Stories as sequences of sentences, and per-sentence coverage in the report.
96
100
  - **[Narration lint](https://nwilbert.github.io/pytest-given/latest/configuration/narration-lint/)**: structural checks that a step's text is honest about its body: empty steps, a `then` that checks nothing, a missing phase.
101
+ - **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and stories, led by their status and checked against the latest run.
97
102
  - **[Agent skills](https://nwilbert.github.io/pytest-given/latest/ai-agents/)**: bundled Agent Skills for authoring, navigating and reviewing narrated tests, installable with one command.
98
103
 
99
104
  The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
@@ -6,22 +6,23 @@ When the lint is off, it costs nothing: pytest-given records nothing extra, and
6
6
 
7
7
  ## Rules
8
8
 
9
- Each rule has a default severity. A `warn` finding is printed in the terminal summary. An `error` finding is printed too, and also fails the run.
9
+ Each rule has a default severity. A `warn` lint finding is printed in the terminal summary. An `error` lint finding is printed too, and also fails the run.
10
10
 
11
11
  | Rule | Default | Catches |
12
12
  |------|---------|---------|
13
13
  | `empty-step` | `error` | A step whose body does nothing: it only contains constants or `pass`, or, for `when` and `then`, only an `attach(...)` call. |
14
14
  | `then-without-check` | `error` | A `then` without an `assert` or a checking call. Checking calls are calls whose name starts with `assert`, and `pytest.raises`, `pytest.warns` and `pytest.fail`. Nothing else counts, not even `pytest.approx`. |
15
+ | `conditional-check` | `warn` | A `then` whose checks all sit under an `if`, a loop, a `match` or an `except`, so a run can pass it without checking anything. An `if` that calls `pytest.fail` counts as a check, and so does a loop over a literal such as `(a, b)`. |
15
16
  | `missing-phase` | `warn` | A passed scenario that is missing one of the phases Given, When or Then. `@given` fixtures and `Annotated[..., given(...)]` parameters count as `given` steps. A parametrized scenario is checked once, not once per case. |
16
17
  | `check-outside-then` | `warn` | An `assert` inside a `given` or `when`. The `when` part of a `when_then` is allowed to contain one. |
17
18
  | `action-in-then` | `warn` | A scenario where no `when` performs an action, and a `then` performs it inside its assertion instead. |
18
19
  | `unused-interpolation` | `warn` | A `with` step whose text contains a `{name}` (a t-string value or a parameter-table placeholder) that the step's body doesn't use. |
19
20
  | `tag-shadows-term` | `warn` | A scenario tag that matches a glossary term, so the same concept has two names. |
20
- | `dead-term` | `off` | A glossary term that no step, scenario name, or story sentence uses. Turn this on if every glossary term should be used. |
21
+ | `dead-term` | `off` | A glossary term that no step, scenario title, or story sentence uses. Turn this on if every glossary term should be used. |
21
22
 
22
23
  ## Configuration
23
24
 
24
- Change a rule's severity with `given_lint_rules`. Skip findings for specific tests with `given_lint_ignore`: each entry is a node-id pattern (with `*` wildcards), optionally limited to one rule with a `rule-id:` prefix.
25
+ Change a rule's severity with `given_lint_rules`. Skip lint findings for specific tests with `given_lint_ignore`: each entry is a node-id pattern (with `*` wildcards), optionally limited to one rule with a `rule-id:` prefix.
25
26
 
26
27
  ```toml
27
28
  [tool.pytest]
@@ -36,16 +37,18 @@ given_lint_ignore = [
36
37
  ]
37
38
  ```
38
39
 
39
- An ignore entry that no longer matches any finding causes a `stale-ignore` error. This keeps the list from growing out of date.
40
+ An ignore entry that no longer matches any lint finding causes a `stale-ignore` error. This keeps the list from growing out of date.
40
41
 
41
42
  To turn the lint on or off for a single run, pass `--given-lint` or `--no-given-lint`. Both override the `given_lint` setting.
42
43
 
43
44
  ## Output
44
45
 
45
- Each finding is printed on one line, with its severity, rule, test, message, and source location:
46
+ Each lint finding is printed on one line, with its severity, rule, test, message, and source location:
46
47
 
47
48
  ```
48
49
  ============= pytest-given: narration lint (2 findings, 1 error) ==============
49
50
  ERROR empty-step tests/test_shop.py::test_buy given 'a coin' has no code (test_shop.py:12)
50
51
  WARN missing-phase tests/test_shop.py::test_idle missing: when (test_shop.py:31)
51
52
  ```
53
+
54
+ A run with no lint findings prints only the separator, `pytest-given: narration lint (no findings)`, so a clean run is told apart from one where the lint is off.