Merge pull request #3583 from VWS-Python/ci/snapper-semantic-line-breaks

Enforce semantic line breaks with Snapper

Author: adamtheturtle

.snapperrc.toml

@@ -0,0 +1,6 @@
+# These files contain markup constructs that Snapper main does not yet preserve.
+ignore = [
+  "CHANGELOG.rst",
+  "docs/source/differences-to-vws.rst",
+  "docs/source/unverified-behavior.rst",
+]

.vale.ini

@@ -4,7 +4,8 @@ MinAlertLevel = error
 Packages = https://github.com/tbhb/vale-ai-tells/releases/download/v1.29.0/ai-tells.zip
 
 [*.{rst,md}]
-BasedOnStyles = ai-tells
+BasedOnStyles = ai-tells, snapper
+snapper.SemanticLineBreaks = error
 
 # These rules misclassify established technical, example, or release-note prose
 # in this repository. All other ai-tells rules remain enforced.

docs/source/ci-setup.rst

@@ -24,8 +24,7 @@ Create environment variable files for secrets:
    $ cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_1.env
    $ ...
 
-Populate every variable listed in :file:`vuforia_secrets.env.example`.
-Each file needs distinct active Cloud database credentials so concurrent jobs do not modify the same database.
+Populate every variable listed in :file:`vuforia_secrets.env.example`. Each file needs distinct active Cloud database credentials so concurrent jobs do not modify the same database.
 The files can share the inactive Cloud, active and inactive VuMark, and Model Target credentials.
 Add at least as many consecutively numbered files, starting at zero, as there are builds in the GitHub test matrix.
 

docs/source/contributing.rst

@@ -56,8 +56,7 @@ Create an environment variable file for secrets:
    $ cp vuforia_secrets.env.example vuforia_secrets.env
 
 Some tests require Vuforia credentials.
-To run these tests, add the Vuforia credentials to the file :file:`vuforia_secrets.env`.
-See :ref:`connecting-to-vuforia`.
+To run these tests, add the Vuforia credentials to the file :file:`vuforia_secrets.env`. See :ref:`connecting-to-vuforia`.
 
 Then run ``pytest``:
 
@@ -73,14 +72,12 @@ Connecting to Vuforia
 To connect to Vuforia, Vuforia target databases must be created via the Vuforia Web UI.
 Then, secret keys must be set as environment variables.
 
-The test infrastructure allows those keys to be set in the file :file:`vuforia_secrets.env`.
-See :file:`vuforia_secrets.env.example` for the environment variables to set.
+The test infrastructure allows those keys to be set in the file :file:`vuforia_secrets.env`. See :file:`vuforia_secrets.env.example` for the environment variables to set.
 
 Do not use a target database that you are using for other purposes.
 This is because the test suite adds and deletes targets.
 
-To create a target database, first create a license key in the `Vuforia License Manager`_.
-Then, add a database from the `Vuforia Target Manager`_.
+To create a target database, first create a license key in the `Vuforia License Manager`_. Then, add a database from the `Vuforia Target Manager`_.
 
 To find the environment variables to set in the :file:`vuforia_secrets.env` file, visit the Target Database in the `Vuforia Target Manager`_ and view the "Database Access Keys".
 

docs/source/unreleased.rst

@@ -1,8 +1,8 @@
 Unreleased changes
 ==================
 
-Changes that have landed on the main branch but are not yet part of a
-tagged release.  These entries are assembled into the
+Changes that have landed on the main branch but are not yet part of a tagged release.
+These entries are assembled into the
 :doc:`changelog` when the next release is published.
 
 .. towncrier-draft-entries::

prek.toml

@@ -407,6 +407,19 @@ hooks = [
     additional_dependencies = ["uv==0.11.7"],
     stages = ["pre-commit"]
   },
+  {
+    id = "snapper",
+    name = "snapper",
+    entry = "uv run --group=dev snapper --max-width 0 --in-place",
+    language = "python",
+    types_or = [
+      "rst",
+      "markdown"
+    ],
+    require_serial = true,
+    additional_dependencies = ["uv==0.11.7"],
+    stages = ["pre-commit"]
+  },
   {
     id = "vale",
     name = "vale",

pyproject.toml

@@ -99,6 +99,7 @@ dev = [
     # use it to lint shell commands in GitHub workflow files.
     "shellcheck-py==0.11.0.1",
     "shfmt-py==4.1.0",
+    "snapper-fmt==0.11.0",
     "sphinx==9.1.0",
     "sphinx-copybutton==0.5.2",
     "sphinx-lint==1.0.2",

styles/snapper/LongProseLine.yml

@@ -0,0 +1,11 @@
+---
+# Vale style rule: flag prose lines that are suspiciously long.
+# Likely indicates wrapped text that should use semantic line breaks.
+extends: existence
+message: Prose line exceeds 120 characters. Consider running 'snapper' to break at
+  sentence boundaries.
+level: suggestion
+scope: paragraph
+# This catches lines > 120 chars that contain a period followed by a space.
+# Pure code or URLs are less likely to match.
+tokens: ['.{120,}']

styles/snapper/SemanticLineBreaks.yml

@@ -0,0 +1,11 @@
+---
+# Vale style rule: flag lines containing multiple sentences.
+# These should be broken at sentence boundaries.
+extends: existence
+message: Line contains multiple sentences. Run 'snapper --check' or reformat with
+  'snapper --in-place'.
+level: warning
+scope: paragraph
+# Match a sentence-ending punctuation followed by a space and a capital letter
+# on the same line (indicating two sentences on one line).
+tokens: ['[.!?]\\s+[A-Z]']