pytest-given 0.5.2__tar.gz → 0.6.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 (221) hide show
  1. {pytest_given-0.5.2 → pytest_given-0.6.0}/AGENTS.md +12 -13
  2. {pytest_given-0.5.2 → pytest_given-0.6.0}/CHANGELOG.md +33 -1
  3. pytest_given-0.6.0/GLOSSARY.md +122 -0
  4. {pytest_given-0.5.2 → pytest_given-0.6.0}/PKG-INFO +9 -5
  5. {pytest_given-0.5.2 → pytest_given-0.6.0}/README.md +8 -4
  6. {pytest_given-0.5.2 → pytest_given-0.6.0}/docs/site/configuration/narration-lint.md +2 -0
  7. {pytest_given-0.5.2 → pytest_given-0.6.0}/noxfile.py +65 -33
  8. {pytest_given-0.5.2 → pytest_given-0.6.0}/pyproject.toml +4 -4
  9. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +2 -2
  10. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +8 -4
  11. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +21 -19
  12. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md +2 -0
  13. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/parameter-tables.md +3 -2
  14. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +3 -3
  15. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +1 -1
  16. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-citing/SKILL.md +11 -7
  17. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-citing/references/repair.md +2 -2
  18. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +1 -1
  19. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +8 -4
  20. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +5 -2
  21. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/hygiene.md +2 -0
  22. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/__init__.py +6 -2
  23. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/__init__.py +13 -12
  24. pytest_given-0.6.0/src/pytest_given/capture/definition_refs.py +55 -0
  25. pytest_given-0.6.0/src/pytest_given/capture/file_glossary.py +154 -0
  26. pytest_given-0.6.0/src/pytest_given/capture/glossary.py +433 -0
  27. pytest_given-0.6.0/src/pytest_given/capture/glossary_resolution.py +34 -0
  28. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/kind_inference.py +1 -1
  29. pytest_given-0.6.0/src/pytest_given/capture/markdown_glossary.py +284 -0
  30. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/process_state.py +13 -8
  31. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/source.py +13 -2
  32. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/story.py +11 -82
  33. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/template.py +7 -3
  34. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/traceback.py +25 -11
  35. pytest_given-0.6.0/src/pytest_given/citations/check.py +325 -0
  36. pytest_given-0.5.2/src/pytest_given/citations/narrated.py → pytest_given-0.6.0/src/pytest_given/citations/details.py +32 -17
  37. pytest_given-0.6.0/src/pytest_given/citations/link_checks.py +410 -0
  38. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/citations/markdown_links.py +19 -0
  39. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/citations/targets.py +34 -5
  40. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/cli/report.py +32 -4
  41. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/cli/skills.py +1 -1
  42. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/checks.py +65 -7
  43. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/columns.py +44 -25
  44. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/context.py +5 -0
  45. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/group.py +10 -22
  46. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/percase.py +4 -2
  47. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/templatize.py +32 -20
  48. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/lint/__init__.py +1 -1
  49. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/lint/ast_rules.py +1 -1
  50. pytest_given-0.5.2/src/pytest_given/lint/base.py → pytest_given-0.6.0/src/pytest_given/lint/catalog.py +4 -0
  51. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/lint/config.py +1 -1
  52. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/lint/runner.py +1 -1
  53. pytest_given-0.6.0/src/pytest_given/lint/runtime_rules.py +360 -0
  54. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/lint/summary.py +1 -1
  55. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/markdown/__init__.py +32 -3
  56. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/markdown/blocks.py +61 -9
  57. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/markdown/plain_text.py +8 -0
  58. pytest_given-0.5.2/src/pytest_given/report/inline_markdown.py → pytest_given-0.6.0/src/pytest_given/markdown/rendering.py +13 -19
  59. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/markdown/spans.py +16 -0
  60. pytest_given-0.6.0/src/pytest_given/markdown/writing.py +74 -0
  61. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/__init__.py +41 -7
  62. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/narration.py +82 -15
  63. pytest_given-0.6.0/src/pytest_given/model/report_order.py +33 -0
  64. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/schema.py +85 -12
  65. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/serde.py +54 -8
  66. pytest_given-0.6.0/src/pytest_given/model/session_capture.py +38 -0
  67. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/text.py +29 -1
  68. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/__init__.py +9 -1
  69. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/collection.py +13 -4
  70. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/options.py +25 -13
  71. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/session.py +63 -37
  72. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/state.py +25 -2
  73. pytest_given-0.6.0/src/pytest_given/plugin/workers.py +115 -0
  74. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/__init__.py +5 -1
  75. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/citation_index.py +79 -61
  76. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/console.py +5 -0
  77. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/coverage.py +10 -10
  78. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/glossary_view.py +118 -17
  79. pytest_given-0.5.2/src/pytest_given/report/text.py → pytest_given-0.6.0/src/pytest_given/report/glyphs.py +1 -1
  80. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/html_renderer.py +121 -55
  81. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/link_text.py +12 -10
  82. pytest_given-0.6.0/src/pytest_given/report/md_narration.py +68 -0
  83. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/md_renderer.py +33 -4
  84. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/sinks.py +36 -1
  85. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/_macros.html.j2 +1 -1
  86. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/app.js +151 -66
  87. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/report.html.j2 +158 -81
  88. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/styles.css +39 -9
  89. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/conftest.py +7 -3
  90. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/test_cli.py +126 -14
  91. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/test_cli_citations.py +38 -1
  92. pytest_given-0.5.2/tests/integration/test_skills_cli.py → pytest_given-0.6.0/tests/integration/test_cli_skills.py +1 -1
  93. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/test_plugin.py +421 -97
  94. pytest_given-0.6.0/tests/integration/test_plugin_file_glossary.py +169 -0
  95. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/test_plugin_lint.py +84 -0
  96. pytest_given-0.6.0/tests/integration/test_plugin_xdist.py +456 -0
  97. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/ubiquitous_language.py +3 -3
  98. pytest_given-0.6.0/tests/unit/capture/test_definition_refs.py +81 -0
  99. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_file_glossary.py +254 -45
  100. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_glossary.py +187 -32
  101. pytest_given-0.6.0/tests/unit/capture/test_glossary_resolution.py +88 -0
  102. pytest_given-0.6.0/tests/unit/capture/test_markdown_glossary.py +640 -0
  103. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_story.py +5 -51
  104. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_template.py +31 -7
  105. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_traceback_parser.py +12 -1
  106. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citation_reports.py +49 -0
  107. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citations/test_check.py +467 -8
  108. pytest_given-0.5.2/tests/unit/citations/test_narrated.py → pytest_given-0.6.0/tests/unit/citations/test_details.py +78 -20
  109. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citations/test_targets.py +21 -2
  110. {pytest_given-0.5.2/tests/unit → pytest_given-0.6.0/tests/unit/grouping}/test_grouping.py +369 -9
  111. {pytest_given-0.5.2/tests/unit → pytest_given-0.6.0/tests/unit/grouping}/test_percase.py +45 -2
  112. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/lint/test_ast_rules.py +36 -7
  113. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/lint/test_config.py +1 -1
  114. pytest_given-0.6.0/tests/unit/lint/test_runtime_rules.py +680 -0
  115. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/lint/test_summary.py +1 -1
  116. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/markdown/test_blocks.py +56 -1
  117. pytest_given-0.6.0/tests/unit/markdown/test_rendering.py +43 -0
  118. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/markdown/test_spans.py +12 -0
  119. pytest_given-0.6.0/tests/unit/markdown/test_writing.py +45 -0
  120. pytest_given-0.6.0/tests/unit/model/test_narration.py +251 -0
  121. pytest_given-0.6.0/tests/unit/model/test_report_order.py +74 -0
  122. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/model/test_schema.py +107 -19
  123. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/model/test_serde.py +132 -1
  124. pytest_given-0.6.0/tests/unit/model/test_session_capture.py +59 -0
  125. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/model/test_text.py +22 -0
  126. pytest_given-0.6.0/tests/unit/plugin/__init__.py +0 -0
  127. {pytest_given-0.5.2/tests/unit → pytest_given-0.6.0/tests/unit/plugin}/test_plugin.py +1 -1
  128. pytest_given-0.6.0/tests/unit/report/__init__.py +0 -0
  129. pytest_given-0.6.0/tests/unit/report/term_refs.py +30 -0
  130. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_citation_index.py +158 -51
  131. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_coverage.py +10 -10
  132. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_glossary_view.py +219 -2
  133. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_html_renderer.py +300 -36
  134. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_link_text.py +30 -0
  135. pytest_given-0.5.2/tests/unit/report/test_markdown_writer.py → pytest_given-0.6.0/tests/unit/report/test_md_narration.py +28 -47
  136. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_md_renderer.py +46 -1
  137. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_sinks.py +106 -0
  138. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_story_view.py +26 -4
  139. pytest_given-0.5.2/tests/unit/report/test_inline_markdown.py → pytest_given-0.6.0/tests/unit/report/test_title_spans.py +8 -45
  140. pytest_given-0.6.0/tests/unit/test_architecture.py +211 -0
  141. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/test_project_glossary.py +1 -1
  142. {pytest_given-0.5.2 → pytest_given-0.6.0}/uv.lock +265 -166
  143. pytest_given-0.5.2/GLOSSARY.md +0 -116
  144. pytest_given-0.5.2/src/pytest_given/capture/discovery.py +0 -68
  145. pytest_given-0.5.2/src/pytest_given/capture/file_glossary.py +0 -103
  146. pytest_given-0.5.2/src/pytest_given/capture/glossary.py +0 -295
  147. pytest_given-0.5.2/src/pytest_given/capture/markdown_glossary.py +0 -121
  148. pytest_given-0.5.2/src/pytest_given/citations/check.py +0 -702
  149. pytest_given-0.5.2/src/pytest_given/lint/runtime_rules.py +0 -177
  150. pytest_given-0.5.2/src/pytest_given/report/markdown_writer.py +0 -105
  151. pytest_given-0.5.2/tests/integration/test_plugin_file_glossary.py +0 -60
  152. pytest_given-0.5.2/tests/unit/capture/test_discovery.py +0 -119
  153. pytest_given-0.5.2/tests/unit/capture/test_markdown_glossary.py +0 -265
  154. pytest_given-0.5.2/tests/unit/lint/test_runtime_rules.py +0 -343
  155. pytest_given-0.5.2/tests/unit/model/test_narration.py +0 -120
  156. {pytest_given-0.5.2 → pytest_given-0.6.0}/.gitignore +0 -0
  157. {pytest_given-0.5.2 → pytest_given-0.6.0}/LICENSE.md +0 -0
  158. {pytest_given-0.5.2 → pytest_given-0.6.0}/THIRD-PARTY-LICENSES +0 -0
  159. {pytest_given-0.5.2 → pytest_given-0.6.0}/conftest.py +0 -0
  160. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +0 -0
  161. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +0 -0
  162. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/collector.py +0 -0
  163. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/scenario.py +0 -0
  164. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/capture/steps.py +0 -0
  165. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/citations/__init__.py +0 -0
  166. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/cli/__init__.py +0 -0
  167. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/cli/citations.py +0 -0
  168. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/__init__.py +0 -0
  169. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/grouping/attachments.py +0 -0
  170. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/errors.py +0 -0
  171. /pytest_given-0.5.2/src/pytest_given/model/runtime.py → /pytest_given-0.6.0/src/pytest_given/model/raw_params.py +0 -0
  172. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/model/report_url.py +0 -0
  173. /pytest_given-0.5.2/src/pytest_given/model/steps.py → /pytest_given-0.6.0/src/pytest_given/model/step_tree.py +0 -0
  174. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/case_ids.py +0 -0
  175. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/fixtures.py +0 -0
  176. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/plugin/runtest.py +0 -0
  177. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/py.typed +0 -0
  178. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/function_source.py +0 -0
  179. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/palette.py +0 -0
  180. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/slugs.py +0 -0
  181. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/source_link.py +0 -0
  182. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/staged_write.py +0 -0
  183. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/story_view.py +0 -0
  184. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/alpine.min.js +0 -0
  185. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/fonts/source-code-pro-latin-wght-normal.woff2 +0 -0
  186. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/fonts/source-sans-3-latin-wght-normal.woff2 +0 -0
  187. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/templates/logo.svg +0 -0
  188. {pytest_given-0.5.2 → pytest_given-0.6.0}/src/pytest_given/report/theme.py +0 -0
  189. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/__init__.py +0 -0
  190. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/__init__.py +0 -0
  191. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/test_lazy_imports.py +0 -0
  192. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/integration/test_plugin_session_isolation.py +0 -0
  193. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/__init__.py +0 -0
  194. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/__init__.py +0 -0
  195. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_collector.py +0 -0
  196. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_kind_inference.py +0 -0
  197. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_rootdir_isolation.py +0 -0
  198. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_source.py +0 -0
  199. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/capture/test_step_descriptor.py +0 -0
  200. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citations/__init__.py +0 -0
  201. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citations/fixtures/citation-forms.md +0 -0
  202. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citations/test_markdown_links.py +0 -0
  203. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/citations/test_markdown_links_oracle.py +0 -0
  204. {pytest_given-0.5.2/tests/unit/lint → pytest_given-0.6.0/tests/unit/grouping}/__init__.py +0 -0
  205. {pytest_given-0.5.2/tests/unit/markdown → pytest_given-0.6.0/tests/unit/lint}/__init__.py +0 -0
  206. {pytest_given-0.5.2/tests/unit/model → pytest_given-0.6.0/tests/unit/markdown}/__init__.py +0 -0
  207. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/markdown/test_plain_text.py +0 -0
  208. {pytest_given-0.5.2/tests/unit/report → pytest_given-0.6.0/tests/unit/model}/__init__.py +0 -0
  209. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/model/test_errors.py +0 -0
  210. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/model/test_report_url.py +0 -0
  211. /pytest_given-0.5.2/tests/unit/model/test_steps.py → /pytest_given-0.6.0/tests/unit/model/test_step_tree.py +0 -0
  212. {pytest_given-0.5.2/tests/unit → pytest_given-0.6.0/tests/unit/plugin}/test_plugin_traceback.py +0 -0
  213. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/app_data.py +0 -0
  214. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_function_source.py +0 -0
  215. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_palette.py +0 -0
  216. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_slugs.py +0 -0
  217. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_source_link.py +0 -0
  218. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_staged_write.py +0 -0
  219. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/report/test_theme.py +0 -0
  220. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/test_quickstart.py +0 -0
  221. {pytest_given-0.5.2 → pytest_given-0.6.0}/tests/unit/test_skills_data.py +0 -0
@@ -16,7 +16,7 @@ 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), `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`.
19
+ `uv run nox` runs the default gate — `format`, `lint`, `mypy`, `coverage` (the test suite, held to 100% coverage), `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 coverage`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
20
20
 
21
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.
@@ -30,11 +30,7 @@ uv sync --group dev
30
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.
31
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
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.
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).
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.
36
- - `docs/site/assets/report-screenshot-{light,dark}.png`, shown on the README and the Home page, are captured by hand: the Hotel booking report at a 1120×588 viewport and device scale 2, with *Cancelling a paid booking refunds it and notifies the guest* expanded, one capture per setting of the report's theme switch. Retake both when the report's look changes.
37
- - 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`.
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). Before changing anything under `docs/site/`, the README's diagram or its screenshots, read [docs/site-development.md](docs/site-development.md): staging, the derived diagram, the screenshot recipe, self-hosted fonts.
38
34
 
39
35
  ## Releasing
40
36
 
@@ -43,10 +39,11 @@ Releases go to PyPI via a manually dispatched [Release workflow](.github/workflo
43
39
  ## Architecture
44
40
 
45
41
  `src/pytest_given/` is seven library subpackages plus two entry points, with a
46
- strict dependency direction (convention, not lint-enforced):
42
+ strict dependency direction (held by `tests/unit/test_architecture.py`):
47
43
 
48
44
  ```
49
- markdown/ the leaf — reading Markdown: blocks, tables, inline spans
45
+ markdown/ the leaf — reading Markdown (blocks, tables, inline
46
+ spans), writing spans back, rendering them as HTML
50
47
  model/ schema, serde, errors, shared text rules
51
48
  capture/ lint/ report/ each on model/ only, never on each other
52
49
  grouping/ on model/ + capture/
@@ -65,9 +62,10 @@ What no filename tells you:
65
62
  a bare `pytest` failing on one is the point, not a side effect.
66
63
  - `capture/` imports pytest nowhere, so all of it is unit-testable without a
67
64
  session; a stray step warns with `model.PytestGivenWarning`, not pytest's.
68
- - `citations/` reads and edits the user's Markdown documents; what a citation
69
- should say is `report`'s `CitationIndex`, since the HTML's copy buttons write
70
- the same lines.
65
+ - `citations/` reads and edits the user's Markdown documents. What a citation
66
+ should say comes from `report`: its glyph, link text and summary from
67
+ `CitationIndex`, since the HTML's copy buttons write the same lines, and a
68
+ `<details>` citation's body from `citation_body_md`.
71
69
  - Each package exposes the *whole* job, not its parts: `report.emit_sinks`
72
70
  (render → write → discard-on-failure, so a failure leaves no half-written
73
71
  report), `lint.run_lint` and `citations.check_citations` (every document
@@ -108,19 +106,20 @@ Before merging changes to narrated tests, run the `pytest-given-reviewing` skill
108
106
 
109
107
  What is specific to this repo's self-report:
110
108
 
111
- - 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).
109
+ - The glossary handle is `pg` — `GLOSSARY.md` loaded as a `TableGlossary` in `tests/ubiquitous_language.py`. Term-rename mechanics live under [Conventions](#conventions); regeneration and lint gating under [Quality gates](#quality-gates).
112
110
  - **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.
113
111
 
114
112
  ## Conventions
115
113
 
116
114
  - 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.
117
115
  - **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.
118
- - 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.
116
+ - 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 Markdown glossary both carry no such subclass.
119
117
  - Avoid `Any` — use precise types, generics, `TYPE_CHECKING` imports, or `ContextVar[T]` over untyped `threading.local`.
120
118
  - 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.
121
119
  - Every package `src/` imports is a declared dependency in `pyproject.toml`, even one another dependency already brings in.
122
120
  - 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).
123
121
  - **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).
122
+ - Every `pytest-given` subcommand exits 0 when it is done with nothing to report, 1 when it found something to act on, and 2 when it could not do its job.
124
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.
125
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).
126
125
  - 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).
@@ -11,6 +11,37 @@ form `## [x.y.z] - YYYY-MM-DD`.
11
11
 
12
12
  <!-- --8<-- [start:site] -->
13
13
 
14
+ ## [0.6.0] - 2026-11-21
15
+
16
+ ### Added
17
+
18
+ - A format spec `{flag:true phrase|false phrase}` words a Boolean in a step while the parameter table keeps the Boolean.
19
+ - Glossary sections: `Glossary.section(name)` and a Markdown glossary's headings group terms, and the Glossary tab groups and filters by them.
20
+ - `ParagraphGlossary` loads a `GLOSSARY.md` written as `**Term**:` paragraphs with optional `_Avoid_:` lines.
21
+ - Avoided words: `avoid=` on a term declaration, a `TableGlossary`'s `avoid_column` and a `ParagraphGlossary`'s `_Avoid_:` line list a term's rejected synonyms, which the term's card shows and the `avoided-word` lint rule, `warn` by default, flags in a step, a scenario title or a story sentence.
22
+ - Term citations: `citations check` and `update` read `#view=glossary&term=<id>` or `#term=<id>` as a citation of a term, with a tag's glyph and summary, a `<details markdown="1">` one carrying the term's definition, and a Glossary term row in the HTML report gets the copy button with **Copy citation** and **Copy defining citation**.
23
+ - A bold term name in a glossary definition is a definition ref, which the HTML report's Glossary tab renders as a term ref that opens the named term, and the `unresolved-definition-ref` lint rule, `warn` by default, flags a bold span that names no term.
24
+ - `pytest-given report --glossary-only` renders an HTML report with only the Glossary tab.
25
+ - A pytest-xdist run (`-n`) writes reports and runs the narration lint, choosing `--dist loadfile` when no `--dist` is given; any other `--dist` still stops with a usage error.
26
+
27
+ ### Changed
28
+
29
+ - **Breaking.** A format spec with one `|` and text on both sides now only accepts a `bool`, so `{when:%H|%M}` on a `datetime` raises `PytestGivenError`. Assign the text to a local variable and interpolate that instead.
30
+ - **Breaking.** `FileGlossary` is renamed `TableGlossary`, and a term repeated under two headings of a Markdown glossary now raises, identical rows included. Rename the import and the constructor call, and keep one row of a repeated term.
31
+ - **Breaking.** `pytest-given report` and `pytest-given skills install` now exit 2, not 1, when they cannot do their job, such as an unreadable JSON file or an unwritable destination. A script that tests for exit code 1 on such a failure must test for 2.
32
+ - **Breaking.** A glossary term's `definition` in the JSON report is now an object, which holds the string it used to be in `text` and its definition refs in `parts`. A script reading `.definition` must read `.definition.text`.
33
+ - A plain report link to a glossary term is now checked, so a dead one fails `citations check`.
34
+ - The report lists scenarios by file and then by line, whatever order the tests ran in.
35
+ - The HTML report leaves out the Scenarios tab when the report has no scenarios, and opens on its first remaining view.
36
+ - **Breaking.** pytest-given finds a glossary wherever the suite's modules construct it, not only through a story or a `conftest.py`, and raises `PytestGivenError` when they construct two. Construct the glossary once and import it wherever it is used.
37
+
38
+ ### Fixed
39
+
40
+ - Following a term ref to the HTML report's Glossary tab scrolls to the term, clearing the tab's search and filters when they hide it.
41
+ - A report link whose `#status=` names only statuses the report doesn't know now shows every scenario instead of none.
42
+ - A failure raised while rendering a step's interpolation, such as a bad format spec, no longer shows a pytest-given frame in the report's traceback.
43
+ - A narrated citation of a scenario with no steps now has an empty body instead of blank lines, which `citations update` rewrites.
44
+
14
45
  ## [0.5.2] - 2026-11-07
15
46
 
16
47
  ### Changed
@@ -479,7 +510,8 @@ First public release.
479
510
  - Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
480
511
  the wheel and version-matched to the plugin.
481
512
 
482
- [Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.5.2...HEAD
513
+ [Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.6.0...HEAD
514
+ [0.6.0]: https://github.com/nwilbert/pytest-given/compare/v0.5.2...v0.6.0
483
515
  [0.5.2]: https://github.com/nwilbert/pytest-given/compare/v0.5.1...v0.5.2
484
516
  [0.5.1]: https://github.com/nwilbert/pytest-given/compare/v0.5.0...v0.5.1
485
517
  [0.5.0]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...v0.5.0
@@ -0,0 +1,122 @@
1
+ # Glossary
2
+
3
+ Canonical vocabulary for pytest-given. Use these terms in code, docs, commit messages, and conversation; flag inconsistencies in review.
4
+
5
+ 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.
6
+
7
+ **Update rule:** rename or repurpose a term → update this file in the same commit.
8
+
9
+ ## Core test model
10
+
11
+ | Term | Meaning |
12
+ |---|---|
13
+ | Scenario | A test that narrates the rule it demonstrates, marked with `@scenario`. Tests without the mark stay out of the report. |
14
+ | Scenario title | The statement of the rule a **Scenario** demonstrates. Not the test function's name, which the **Node ID** carries. |
15
+ | Step | A unit of narration in one **Phase**. Steps nest and may carry **Attachments**, but have no status or error of their own: a failure belongs to the **Scenario**, and to its **Case** in a **Parameter table**. |
16
+ | Narration | The human-readable text on a step or scenario title, which may mix plain text with values, placeholders and **term refs**. |
17
+ | Phase | The category of a step: `given`, `when`, or `then`. A step has exactly one phase. |
18
+ | when_then | One block that narrates a `when` action and its `then` outcome as two sibling steps. Used mainly to narrate an expected raise, so the action and its outcome stay distinct steps. |
19
+ | Tag | A free-form label on a scenario. A `/` nests it: `ticket/ABC-123` sits under `ticket`. |
20
+ | Attachment | A labeled piece of text or JSON bound to the step being narrated. |
21
+
22
+ ## Parametrization
23
+
24
+ | Term | Meaning |
25
+ |---|---|
26
+ | Parametrized scenario | A **Scenario** whose test is parametrized, so it runs once per **Case**. pytest-given **groups** the results. |
27
+ | Case | One row of a parametrized scenario: its node ID, its 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 table of **cases** and columns. A column is a `param` (a parametrize input), a `derived` (a narrated value that varies across cases) or an `attachment` (an **attachment** whose payload varies). |
30
+ | Boolean phrase | Either of the two texts that word a Boolean in a step. Written as a phrase spec, a format spec holding the true phrase, a `\|` and the false phrase: `{pinned:pins it\|does not pin it}`. The step shows both phrases, and the **Parameter table** keeps the Boolean. |
31
+ | Group | Collapsing the **cases** 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. |
32
+ | Templatize | Derive the grouped-template step text by comparing every comparable **case**: what all of them share stays inline, and anything that varies points at a **parameter-table** column. The baseline comes from the first passed case, and every other passed case must narrate that same template — a failed case too, over the steps it shares with the baseline. |
33
+
34
+ ## Fixtures and recording
35
+
36
+ | Term | Meaning |
37
+ |---|---|
38
+ | Step fixture | A pytest fixture that narrates its setup as a `given` **Step**. A fixture cannot narrate `when` or `then`. |
39
+ | 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. |
40
+ | 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. |
41
+ | Fixture recording | The steps and attachments a **step fixture** narrates during setup. A generator fixture's teardown records nothing — it refuses steps and attachments. |
42
+ | Graft | Attaching a **fixture recording** into the **active scenario**'s step tree at the moment its host test starts. |
43
+
44
+ ## Collector state
45
+
46
+ | Term | Meaning |
47
+ |---|---|
48
+ | Collector | What gathers a session's scenarios, **fixture recordings** and parameter info. |
49
+ | Active scenario | The scenario currently being recorded into. |
50
+ | Node ID | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). |
51
+ | Step stack | The chain of currently-open steps. Opening a step adds it, and leaving its block removes it. |
52
+
53
+ ## Report
54
+
55
+ | Term | Meaning |
56
+ |---|---|
57
+ | 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. |
58
+ | Renderer | Converts a JSON report into a rendering — a self-contained HTML page or a Markdown document. |
59
+ | 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. |
60
+ | 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. |
61
+ | Source link | A link to a file and line: a scenario's test function, or the declaration of a **Story** or **Term**. |
62
+ | Report link | A Markdown link to a scenario, tag, story or term in the HTML **Report**. Without a glyph it is a plain one, which claims only that its target exists. |
63
+ | Citation | A **Report link** led by its target's status glyph, citing a scenario, tag, story or term from a Markdown document: `✅ [title](<report URL>#scenario=…)`. A tag, story or term citation adds a summary after it, `(5 ✅ · 2 🔵)`. A target the **Report** lacks reads `❓`. |
64
+ | Narrated citation | A **Citation** of a scenario written as a collapsible block, the citation as its summary and the scenario's Markdown narration as its body. |
65
+ | Defining citation | A **Citation** of a term written as a collapsible block, the citation as its summary and the term's definition as its body. |
66
+ | 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. |
67
+ | Theme | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). |
68
+
69
+ ## Narration lint
70
+
71
+ | Term | Meaning |
72
+ |---|---|
73
+ | 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. |
74
+ | 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. |
75
+ | 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. |
76
+ | 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. |
77
+
78
+ ## Domain Storytelling
79
+
80
+ The Domain-Driven Design layer atop the core surface. All terms here are optional features: a test suite can use none, some, or all.
81
+
82
+ Terms follow [Domain Storytelling](https://domainstorytelling.org/quick-start-guide)'s own, where actors and work objects connected by activities form sentences.
83
+
84
+ | Term | Meaning |
85
+ |---|---|
86
+ | Glossary | The shared vocabulary a domain speaks in: its Ubiquitous Language. |
87
+ | Markdown glossary | A glossary loaded from a Markdown file: a `TableGlossary` from GFM pipe tables, or a `ParagraphGlossary` from **term paragraphs**. |
88
+ | Term paragraph | A term in a `ParagraphGlossary`, written as one paragraph: `**Term**:`, its definition, and an optional `_Avoid_:` line, the format of Matt Pocock's skills. |
89
+ | Glossary section | A named group of terms: the heading a **Markdown glossary** term sits under, or the `g.section(...)` a code glossary declares it through. The Glossary tab groups and filters by it. |
90
+ | Avoided word | A rejected synonym a **term** lists, which the `avoided-word` lint rule flags in narration. An avoid entry may add a parenthesized note, which the report shows and the lint ignores. |
91
+ | Deferred term | A term handed over before its kind is settled: what `g('foo')` and `g['foo']` on a code glossary return, and a **Markdown glossary** lookup of a row with no declared kind. **Kind inference** settles it later. |
92
+ | Term | A glossary entry: an **Actor**, **Work Object**, **Activity**, or **kindless** term. Each carries an id (slug), a canonical name, a kind unless kindless, an optional definition, an optional **glossary section** and any **avoided words**. |
93
+ | Handle | What a glossary hands back for a **term**, the same 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. |
94
+ | 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**. |
95
+ | Actor | A glossary term for a participant in the domain (e.g., *Guest*). |
96
+ | Work Object | A glossary term for a thing acted on (e.g., *Room*, *Booking*). |
97
+ | 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*. |
98
+ | Term ref | An occurrence of a term inside narration, a clause or a definition. |
99
+ | Definition ref | A bold span in a glossary definition that names a term of the same glossary, by its canonical name or **S-form** in any case. The report renders it as a **term ref**. |
100
+ | Instance | A named refinement of an **Actor** or **Work Object** (e.g., `guest('Alice')` is an instance of the *Guest* actor). |
101
+ | 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*). |
102
+ | Story | A named flow modeled as a sequence of **sentences**. Stories are the unit of **coverage**. |
103
+ | 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 and optionally named, a name that stays put when rows are inserted. Usually one **clause**; several when the sentence has several arrows under one number. |
104
+ | Clause part | A piece of a **clause**'s prose: a **term ref**, or a bare clause word. A bare clause word — a node label or edge connective — 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. |
105
+ | Clause | One linear walk through a **sentence**'s arrows, a node/edge alternation starting actor → verb → noun. 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. |
106
+ | 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. |
107
+ | 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. |
108
+ | Pin | What a sentence's **Handle** passed to `pins=` is recorded as, the way a term handle in narration is recorded as a **term ref**: a reference to 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. |
109
+ | Coverage | The "did this scenario touch that sentence" relation. 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. |
110
+ | Kind inference | The pass 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**. |
111
+ | Kindless | A term with no kind, because **kind inference** finds no story **slot** to infer from (a term used only in t-string steps, never in a sentence). |
112
+ | Undefined | A term with no definition. Orthogonal to **kindless**. |
113
+
114
+ ## Collaboration
115
+
116
+ The people and machines collaborating on a pytest-given test suite — the cast of the project's own domain story (defined in `tests/ubiquitous_language.py`).
117
+
118
+ | Term | Meaning |
119
+ |---|---|
120
+ | Developer | Person who writes the application code and — together with the **Agent** — the scenarios; curates the glossary with the **Domain Expert**. |
121
+ | Domain Expert | Person who owns the domain knowledge and the ubiquitous language; source of domain stories and reviewer of scenarios and reports. A stakeholder in the broad sense. |
122
+ | Agent | AI coding agent that authors and maintains scenarios alongside the **Developer**, guided by the pytest-given skills. |
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pytest-given
3
- Version: 0.5.2
3
+ Version: 0.6.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
@@ -55,7 +55,8 @@ Inspired by [JGiven](https://jgiven.org/) (Java).
55
55
  Live examples:
56
56
  - **[Coffeeshop](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html)**: a tour of the core features.
57
57
  - **[Hotel booking](https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html)**: a glossary and domain stories, with story coverage.
58
- - **[File glossary](https://nwilbert.github.io/pytest-given/latest/examples/file-glossary-booking.html)**: the same, with the glossary kept in a Markdown file.
58
+ - **[Table glossary](https://nwilbert.github.io/pytest-given/latest/examples/table-glossary.html)**: the same, with the glossary kept in a Markdown table.
59
+ - **[Paragraph glossary](https://nwilbert.github.io/pytest-given/latest/examples/paragraph-glossary.html)**: the glossary kept as `**Term**:` paragraphs, with sections and avoided words.
59
60
  - **[Self-report](https://nwilbert.github.io/pytest-given/latest/examples/self-report.html)**: pytest-given's own test suite.
60
61
 
61
62
  ## Quick start
@@ -123,7 +124,10 @@ pytest-given works the other way round: **engineers or their agents write normal
123
124
  Most tests are no longer written by hand. A person describes the behavior they want, in a prompt or a spec, and an AI agent writes the tests along with the code. People review the narrated report first, and the test code behind it where it matters. The diagram shows this loop, and [Working with AI agents](https://nwilbert.github.io/pytest-given/latest/ai-agents/) explains how to set it up.
124
125
 
125
126
  <p align="center">
126
- <img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
127
+ <picture>
128
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram-dark.svg">
129
+ <img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
130
+ </picture>
127
131
  </p>
128
132
 
129
133
  ### Glossary and Domain Storytelling
@@ -132,7 +136,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
132
136
 
133
137
  ### Documents that stay true
134
138
 
135
- 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. `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.
139
+ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags, stories and glossary terms as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run. `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.
136
140
 
137
141
  ## Features
138
142
 
@@ -143,7 +147,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
143
147
  - **[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.
144
148
  - **Reports**: a self-contained [HTML report](https://nwilbert.github.io/pytest-given/latest/html-report/) to browse and share, and a [Markdown report](https://nwilbert.github.io/pytest-given/latest/markdown-report/) for diffs, reviews and agents.
145
149
  - **[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.
146
- - **[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.
150
+ - **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags, stories and glossary terms, led by their status and checked against the latest run.
147
151
  - **[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.
148
152
 
149
153
  The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
@@ -24,7 +24,8 @@ Inspired by [JGiven](https://jgiven.org/) (Java).
24
24
  Live examples:
25
25
  - **[Coffeeshop](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html)**: a tour of the core features.
26
26
  - **[Hotel booking](https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html)**: a glossary and domain stories, with story coverage.
27
- - **[File glossary](https://nwilbert.github.io/pytest-given/latest/examples/file-glossary-booking.html)**: the same, with the glossary kept in a Markdown file.
27
+ - **[Table glossary](https://nwilbert.github.io/pytest-given/latest/examples/table-glossary.html)**: the same, with the glossary kept in a Markdown table.
28
+ - **[Paragraph glossary](https://nwilbert.github.io/pytest-given/latest/examples/paragraph-glossary.html)**: the glossary kept as `**Term**:` paragraphs, with sections and avoided words.
28
29
  - **[Self-report](https://nwilbert.github.io/pytest-given/latest/examples/self-report.html)**: pytest-given's own test suite.
29
30
 
30
31
  ## Quick start
@@ -92,7 +93,10 @@ pytest-given works the other way round: **engineers or their agents write normal
92
93
  Most tests are no longer written by hand. A person describes the behavior they want, in a prompt or a spec, and an AI agent writes the tests along with the code. People review the narrated report first, and the test code behind it where it matters. The diagram shows this loop, and [Working with AI agents](https://nwilbert.github.io/pytest-given/latest/ai-agents/) explains how to set it up.
93
94
 
94
95
  <p align="center">
95
- <img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
96
+ <picture>
97
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram-dark.svg">
98
+ <img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
99
+ </picture>
96
100
  </p>
97
101
 
98
102
  ### Glossary and Domain Storytelling
@@ -101,7 +105,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
101
105
 
102
106
  ### Documents that stay true
103
107
 
104
- 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. `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.
108
+ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags, stories and glossary terms as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run. `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.
105
109
 
106
110
  ## Features
107
111
 
@@ -112,7 +116,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
112
116
  - **[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.
113
117
  - **Reports**: a self-contained [HTML report](https://nwilbert.github.io/pytest-given/latest/html-report/) to browse and share, and a [Markdown report](https://nwilbert.github.io/pytest-given/latest/markdown-report/) for diffs, reviews and agents.
114
118
  - **[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.
115
- - **[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.
119
+ - **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags, stories and glossary terms, led by their status and checked against the latest run.
116
120
  - **[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.
117
121
 
118
122
  The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
@@ -19,6 +19,8 @@ Each rule has a default severity. A `warn` lint finding is printed in the termin
19
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. |
20
20
  | `tag-shadows-term` | `warn` | A scenario tag that matches a glossary term, so the same concept has two names. |
21
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. |
22
+ | `unresolved-definition-ref` | `warn` | A bold span in a glossary definition that names no term of the glossary, often left behind when a term is renamed. Fix the name, or use italics for emphasis. An entry for this rule names the term's id instead of a test: `unresolved-definition-ref: handle`. |
23
+ | `avoided-word` | `warn` | An [avoided word](../guide/glossary.md#avoided-words) of a glossary term, or its S-form, as a whole word in any case, with a hyphen or a space between its words, in the plain text of a scenario title, a step or a story sentence. Term refs, values, code spans and glossary definitions are not checked, but both phrases of a [Boolean phrase](../guide/step-text.md#boolean-phrases) are. Each scenario or story gets one lint finding per avoided word. Use a term ref to the preferred term, the fitting one when the message names several, or reword. If the word is right after all, remove it from the term's avoided words. An entry for this rule names the scenario's node ID or the story's id: `avoided-word: *::test_booking`. |
22
24
 
23
25
  ## Configuration
24
26
 
@@ -36,7 +36,6 @@ nox.options.sessions = [
36
36
  'format',
37
37
  'lint',
38
38
  'mypy',
39
- 'test',
40
39
  'coverage',
41
40
  'citations',
42
41
  'audit',
@@ -136,8 +135,6 @@ def coverage(session: nox.Session) -> None:
136
135
  'pytest_given',
137
136
  '-m',
138
137
  'pytest',
139
- 'tests/unit',
140
- 'tests/integration',
141
138
  )
142
139
  try:
143
140
  session.run('coverage', 'report', '--fail-under', '100', '--show-missing')
@@ -402,9 +399,14 @@ _EXAMPLES = (
402
399
  'Hotel Booking Example',
403
400
  ),
404
401
  _Example(
405
- 'examples/file-glossary-booking/test_file_glossary_booking.py',
406
- 'file-glossary-booking',
407
- 'File Glossary Example',
402
+ 'examples/table-glossary/test_table_glossary.py',
403
+ 'table-glossary',
404
+ 'Table Glossary Example',
405
+ ),
406
+ _Example(
407
+ 'examples/paragraph-glossary/test_paragraph_glossary.py',
408
+ 'paragraph-glossary',
409
+ 'Paragraph Glossary Example',
408
410
  ),
409
411
  )
410
412
  _EXAMPLE_REPORTS = (*(example.slug for example in _EXAMPLES), 'self-report')
@@ -470,7 +472,7 @@ def reports_current(session: nox.Session) -> None:
470
472
 
471
473
  @nox.session
472
474
  def examples(session: nox.Session) -> None:
473
- """Regenerate coffeeshop, hotel-booking, and file-glossary-booking reports."""
475
+ """Regenerate the example reports."""
474
476
  _sync(session, include_project=True)
475
477
  _regenerate_examples(session)
476
478
 
@@ -511,7 +513,7 @@ def _regenerate_examples(session: nox.Session) -> None:
511
513
  'rendering (coffeeshop: test_failing; hotel-booking: gift-card decline case). '
512
514
  'coffeeshop uses --given-all-frames to demonstrate the internal-frames '
513
515
  'toggle; hotel-booking uses the default filter. '
514
- 'file-glossary-booking has no intentional failures.'
516
+ 'table-glossary has no intentional failures.'
515
517
  )
516
518
 
517
519
 
@@ -539,7 +541,7 @@ def _build_docs(session: nox.Session, docs_version: str) -> None:
539
541
  """Stage the files the site embeds, then build it strictly.
540
542
 
541
543
  The staged files are single-sourced elsewhere in the repo: the full-size
542
- diagram the Home page links to (the README copy, see `diagram`), every
544
+ diagram the Home page links to (derived like the README's, see `diagram`), every
543
545
  example's report — rendered from its JSON, so its copy buttons link the
544
546
  `docs_version` being built rather than the committed HTML's `/dev/` —
545
547
  the two upright font faces the report package embeds (the site's italic
@@ -551,7 +553,6 @@ def _build_docs(session: nox.Session, docs_version: str) -> None:
551
553
  """
552
554
  _sync(session, 'docs', include_project=True)
553
555
  staged = [
554
- (_DIAGRAM_README_COPY, _DOCS_SITE / 'assets' / 'pytest-given-diagram-full.svg'),
555
556
  *(
556
557
  (font, _DOCS_SITE / 'assets' / 'fonts' / font.name)
557
558
  for font in sorted(_REPORT_FONTS.glob('*.woff2'))
@@ -562,6 +563,13 @@ def _build_docs(session: nox.Session, docs_version: str) -> None:
562
563
  target.parent.mkdir(parents=True, exist_ok=True)
563
564
  shutil.copyfile(source, target)
564
565
  session.log(f'staged {source} -> {target}')
566
+ # The site has a theme switch, so its full-size view follows the colour scheme.
567
+ _DIAGRAM_FULL_SIZE.write_text(
568
+ _standalone_diagram(_DIAGRAM_TOKENS_LIGHT, _DIAGRAM_TOKENS_DARK),
569
+ encoding='utf-8',
570
+ newline='\n',
571
+ )
572
+ session.log(f'wrote {_DIAGRAM_FULL_SIZE}')
565
573
  for slug in _EXAMPLE_REPORTS:
566
574
  session.run(
567
575
  'pytest-given',
@@ -585,11 +593,16 @@ def docs_build(session: nox.Session) -> None:
585
593
 
586
594
  _DIAGRAM_SOURCE = _DOCS_SITE / 'assets' / 'pytest-given-diagram.svg'
587
595
  _DIAGRAM_FONT = _REPORT_FONTS / 'source-sans-3-latin-wght-normal.woff2'
588
- _DIAGRAM_README_COPY = Path('docs/pytest-given-diagram.svg')
596
+ # The README shows the light copy (the path the released READMEs on PyPI link)
597
+ # and, through a <picture> <source>, the dark one. PyPI strips <source>, and its
598
+ # page stays light whatever the reader's colour scheme.
599
+ _DIAGRAM_README_LIGHT = Path('docs/pytest-given-diagram.svg')
600
+ _DIAGRAM_README_DARK = Path('docs/pytest-given-diagram-dark.svg')
601
+ _DIAGRAM_FULL_SIZE = _DOCS_SITE / 'assets' / 'pytest-given-diagram-full.svg'
589
602
 
590
603
  # The site defines these tokens from the theme's variables (stylesheets/extra.css);
591
- # the README copy has no theme, so it carries the resolved values, light first and
592
- # dark under a prefers-color-scheme query. Keep in step with extra.css.
604
+ # the standalone copies have no theme, so they carry the resolved values. Keep in
605
+ # step with extra.css.
593
606
  _DIAGRAM_TOKENS_LIGHT = {
594
607
  'bg': '#fff',
595
608
  'line': 'rgba(0, 0, 0, 0.55)',
@@ -612,24 +625,40 @@ _DIAGRAM_TOKENS_DARK = {
612
625
  }
613
626
 
614
627
 
615
- def _token_block(tokens: dict[str, str], indent: str) -> str:
616
- return ''.join(
617
- f'{indent} --pg-diagram-{name}: {value};\n' for name, value in tokens.items()
618
- )
619
-
620
-
621
628
  @nox.session(venv_backend='none')
622
629
  def diagram(session: nox.Session) -> None:
623
- """Derive the README's standalone diagram from the site's inline SVG.
630
+ """Derive the README's light and dark diagrams from the site's inline SVG.
631
+
632
+ Rerun after editing the source SVG or the token lists above, and commit the
633
+ result.
634
+ """
635
+ for path, tokens in (
636
+ (_DIAGRAM_README_LIGHT, _DIAGRAM_TOKENS_LIGHT),
637
+ (_DIAGRAM_README_DARK, _DIAGRAM_TOKENS_DARK),
638
+ ):
639
+ path.write_text(_standalone_diagram(tokens), encoding='utf-8', newline='\n')
640
+ session.log(f'wrote {path}')
641
+
642
+
643
+ def _standalone_diagram(
644
+ tokens: dict[str, str], dark_tokens: dict[str, str] | None = None
645
+ ) -> str:
646
+ """The site's SVG made standalone, with `dark_tokens` under prefers-color-scheme.
624
647
 
625
648
  On the site the SVG is inlined, so page CSS supplies the font and the colour
626
- tokens; GitHub and PyPI render the README copy as an image, so it embeds the
627
- Source Sans 3 subset the site already ships and resolves the tokens itself. A pure
628
- text transform: same inputs, same bytes. Rerun after editing the source SVG
629
- or the token lists above, and commit the result.
649
+ tokens; an SVG shown as an image gets neither, so this embeds the Source Sans 3
650
+ subset the site already ships and resolves the tokens. A pure text transform:
651
+ same inputs, same bytes.
630
652
  """
631
653
  source = _DIAGRAM_SOURCE.read_text(encoding='utf-8')
632
654
  font = base64.b64encode(_DIAGRAM_FONT.read_bytes()).decode('ascii')
655
+ dark_query = (
656
+ ''
657
+ if dark_tokens is None
658
+ else ' @media (prefers-color-scheme: dark) {\n'
659
+ ' svg {\n' + _token_block(dark_tokens, ' ') + ' }\n'
660
+ ' }\n'
661
+ )
633
662
  standalone_style = (
634
663
  ' <style>\n'
635
664
  ' @font-face {\n'
@@ -639,12 +668,10 @@ def diagram(session: nox.Session) -> None:
639
668
  ' }\n'
640
669
  ' svg {\n'
641
670
  ' font-family: "Source Sans 3", system-ui, sans-serif;\n'
642
- + _token_block(_DIAGRAM_TOKENS_LIGHT, ' ')
671
+ + _token_block(tokens, ' ')
643
672
  + ' }\n'
644
- ' @media (prefers-color-scheme: dark) {\n'
645
- ' svg {\n' + _token_block(_DIAGRAM_TOKENS_DARK, ' ') + ' }\n'
646
- ' }\n'
647
- ' </style>\n'
673
+ + dark_query
674
+ + ' </style>\n'
648
675
  )
649
676
  header = (
650
677
  '<!-- Generated by `nox -s diagram` from '
@@ -653,7 +680,7 @@ def diagram(session: nox.Session) -> None:
653
680
  open_tag_end = source.index('>\n') + 2
654
681
  artwork_style_end = ' </style>\n'
655
682
  assert source.count(artwork_style_end) == 1
656
- standalone = (
683
+ return (
657
684
  header
658
685
  + source[:open_tag_end].replace(
659
686
  '<svg ', '<svg xmlns="http://www.w3.org/2000/svg" ', 1
@@ -666,8 +693,12 @@ def diagram(session: nox.Session) -> None:
666
693
  + ' <rect width="1000" height="1000" fill="var(--pg-diagram-bg)"/>\n',
667
694
  )
668
695
  )
669
- _DIAGRAM_README_COPY.write_text(standalone, encoding='utf-8', newline='\n')
670
- session.log(f'wrote {_DIAGRAM_README_COPY}')
696
+
697
+
698
+ def _token_block(tokens: dict[str, str], indent: str) -> str:
699
+ return ''.join(
700
+ f'{indent} --pg-diagram-{name}: {value};\n' for name, value in tokens.items()
701
+ )
671
702
 
672
703
 
673
704
  @nox.session
@@ -697,7 +728,8 @@ def docs_deploy(session: nox.Session) -> None:
697
728
  def self_report(session: nox.Session) -> None:
698
729
  """Regenerate the self-documentation report from pytest-given's own backend
699
730
  tests. The @scenario-decorated unit tests narrate the plugin's behavior in
700
- the vocabulary of GLOSSARY.md (loaded as a FileGlossary in tests/conftest.py).
731
+ the vocabulary of GLOSSARY.md, loaded as a TableGlossary in
732
+ tests/ubiquitous_language.py.
701
733
  """
702
734
  _sync(session, 'test', include_project=True)
703
735
  _regenerate_self_report(session)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytest-given"
3
- version = "0.5.2"
3
+ version = "0.6.0"
4
4
  description = "A pytest plugin that generates interactive HTML reports from Given/When/Then annotated tests."
5
5
  readme = "README.md"
6
6
  # PEP 639: an SPDX expression plus the files it refers to. Deliberately no
@@ -57,7 +57,7 @@ lint = ["ruff>=0.15.13"]
57
57
  nox = ["nox>=2026.4.10"]
58
58
  typecheck = ["mypy>=2.1.0", { include-group = "nox" }]
59
59
  coverage = ["coverage>=7.14.0"]
60
- # The suite's own: the xdist refusal runs inner pytester runs with `-n`.
60
+ # The suite's own: the xdist tests run inner pytester runs with `-n`.
61
61
  test = ["pytest-xdist>=3.8.0"]
62
62
  audit = ["pip-audit>=2.10.0"]
63
63
  # only for the example:
@@ -92,14 +92,14 @@ packages = ["src/pytest_given"]
92
92
  # untracked local directories, so this is an allowlist rather than a list of
93
93
  # exclusions. `pyproject.toml`, the readme, and the license files are always
94
94
  # included. GLOSSARY.md is load-bearing: tests/conftest.py loads it as a
95
- # FileGlossary. The narration-lint docs page is listed for the same reason:
95
+ # TableGlossary. The narration-lint docs page is listed for the same reason:
96
96
  # tests/unit/lint/test_config.py checks its rule table against the lint
97
97
  # catalog. `examples/` is deliberately out — 2.6 MB of pre-rendered reports
98
98
  # that no test reads (the eight `examples/` mentions under tests/ are all
99
99
  # string literals), browsable on GitHub instead.
100
100
  [tool.hatch.build.targets.sdist]
101
101
  # Patterns are gitignore-style: a leading slash anchors to the project root.
102
- # Without it, "GLOSSARY.md" also matches examples/file-glossary-booking/GLOSSARY.md.
102
+ # Without it, "GLOSSARY.md" also matches examples/table-glossary/GLOSSARY.md.
103
103
  include = [
104
104
  "/src",
105
105
  "/tests",