feat: --check-fail-msg

Author: nedbat

CHANGELOG.rst

@@ -21,6 +21,9 @@ These are changes to Cog over time.
 Unreleased
 ----------
 
+- Added a ``--check-fail-msg`` option for providing a message as part of the
+  output of a ``--check`` failure.
+
 - Added support for Python 3.14.
 
 

Makefile

@@ -41,11 +41,7 @@ cogdoc:			## Run cog to keep the docs correct.
 	python -m cogapp -r $(COGARGS)
 
 lintdoc:		## Check that the docs are up-to-date.
-	@python -m cogapp --check --diff $(COGARGS); \
-	if [ $$? -ne 0 ]; then \
-		echo 'Docs need to be updated: `make cogdoc`'; \
-		exit 1; \
-	fi
+	@python -m cogapp --check --check-fail-msg='Docs need to be updated: `make cogdoc`' --diff $(COGARGS)
 
 dochtml:		## Build local docs.
 	$(MAKE) -C docs html

cogapp/cogapp.py

@@ -52,6 +52,9 @@
     -z          The end-output marker can be omitted, and is assumed at eof.
     -v          Print the version of cog and exit.
     --check     Check that the files would not change if run again.
+    --check-fail-msg='MSG'
+                If --check fails, include MSG in the output to help devs
+                understand how to run cog in your project.
     --diff      With --check, show a diff of what failed the check.
     --markers='START END END-OUTPUT'
                 The patterns surrounding cog inline instructions. Should
@@ -243,6 +246,7 @@ def __init__(self):
         self.prologue = ""
         self.print_output = False
         self.check = False
+        self.check_fail_msg = None
         self.diff = False
 
     def __eq__(self, other):
@@ -266,6 +270,7 @@ def parse_args(self, argv):
                 "cdD:eI:n:o:rs:p:PUvw:xz",
                 [
                     "check",
+                    "check-fail-msg=",
                     "diff",
                     "markers=",
                     "verbosity=",
@@ -313,6 +318,8 @@ def parse_args(self, argv):
                 self.eof_can_be_end = True
             elif o == "--check":
                 self.check = True
+            elif o == "--check-fail-msg":
+                self.check_fail_msg = a
             elif o == "--diff":
                 self.diff = True
             elif o == "--markers":
@@ -794,7 +801,10 @@ def callable_main(self, argv):
             raise CogUsageError("No files to process")
 
         if self.check_failed:
-            raise CogCheckFailed("Check failed")
+            msg = "Check failed"
+            if self.options.check_fail_msg:
+                msg = f"{msg}: {self.options.check_fail_msg}"
+            raise CogCheckFailed(msg)
 
     def main(self, argv):
         """Handle the command-line execution for cog."""

cogapp/test_cogapp.py

@@ -2210,6 +2210,26 @@ def test_check_bad_with_diff(self):
         self.assertEqual(self.output.getvalue(), reindent_block(output))
         self.assert_made_files_unchanged(d)
 
+    def test_check_bad_with_message(self):
+        d = {
+            "changed.cog": """\
+                //[[[cog
+                cog.outl("goodbye world")
+                //]]]
+                hello world
+                //[[[end]]]
+                """,
+        }
+        make_files(d)
+        self.run_check(
+            ["--check-fail-msg=Run `make cogged` to fix", "changed.cog"], status=5
+        )
+        self.assertEqual(
+            self.output.getvalue(),
+            "Checking changed.cog  (changed)\nCheck failed: Run `make cogged` to fix\n",
+        )
+        self.assert_made_files_unchanged(d)
+
     def test_check_mixed(self):
         d = {
             "unchanged.cog": """\

docs/running.rst

@@ -56,6 +56,9 @@ Cog is a command-line utility which takes arguments in standard form.
         -z          The end-output marker can be omitted, and is assumed at eof.
         -v          Print the version of cog and exit.
         --check     Check that the files would not change if run again.
+        --check-fail-msg='MSG'
+                    If --check fails, include MSG in the output to help devs
+                    understand how to run cog in your project.
         --diff      With --check, show a diff of what failed the check.
         --markers='START END END-OUTPUT'
                     The patterns surrounding cog inline instructions. Should
@@ -66,7 +69,7 @@ Cog is a command-line utility which takes arguments in standard form.
                     1 lists only changed files, 0 lists no files.
         -h, --help  Print this help.
 
-.. {{{end}}} (sum: VLpx2/79qp)
+.. {{{end}}} (sum: HvoLNTo8/2)
 
 In addition to running cog as a command on the command line, you can also
 invoke it as a module with the Python interpreter:
@@ -217,6 +220,10 @@ check that your files have been updated properly.
 The ``--diff`` option will show a unified diff of the change that caused
 ``--check`` to fail.
 
+The ``--check-fail-msg`` option can be used to provide a message as part of the
+output if ``--check`` fails.  This can be used to give instructions about how
+to run cog in your project to fix the problem.
+
 
 Output line suffixes
 --------------------