test/doc: add more tests of star behavior, and document it.

CHANGES.rst

@@ -20,8 +20,15 @@ development at the same time, such as 4.5.x and 5.0.
 Unreleased
 ----------
 
-Nothing yet.
-
+- The semantics of stars in file patterns has been clarified in the docs.  A
+  leading or trailing star component matches any number of path components,
+  like a double star would.  This is different than the behavior of a star in
+  the middle of a pattern.  This discrepancy was `identified by Sviatoslav
+  Sydorenko <starbad_>`_, who `provided patient detailed diagnosis
+  <pull 1650_>`_ and graciously agreed to a pragmatic resolution.
+
+.. _starbad: https://github.com/nedbat/coveragepy/issues/1407#issuecomment-1631085209
+.. _issue 1646: https://github.com/nedbat/coveragepy/issues/1646
 
 .. scriv-start-here
 
@@ -32,7 +39,7 @@ Version 7.3.0 — 2023-08-12
 
 - Added a :meth:`.Coverage.collect` context manager to start and stop coverage
   data collection.
-  
+
 - Dropped support for Python 3.7.
 
 - Fix: in unusual circumstances, SQLite cannot be set to asynchronous mode.

doc/source.rst

@@ -181,12 +181,16 @@ File patterns
 File path patterns are used for include and omit, and for combining path
 remapping.  They follow common shell syntax:
 
-- ``*`` matches any number of file name characters, not including the directory
-  separator.
-
 - ``?`` matches a single file name character.
 
-- ``**`` matches any number of nested directory names, including none.
+- ``*`` as part of a path component matches any number of file name characters,
+  not including the directory separator: one path component.
+
+- ``*`` as the first or last path component matches anything including
+  directory separators: any number of path components, including none, like
+  ``**``.
+
+- ``**`` matches any number of path components, including none.
 
 - Both ``/`` and ``\`` will match either a slash or a backslash, to make
   cross-platform matching easier.

tests/test_files.py

@@ -235,9 +235,24 @@ def globs_to_regex_params(
         ),
         globs_to_regex_params(
             ["*/foo"], case_insensitive=False, partial=True,
-            matches=["abc/foo/hi.py", "foo/hi.py"],
+            matches=["abc/foo/hi.py", "foo/hi.py", "abc/def/foo/hi.py"],
             nomatches=["abc/xfoo/hi.py"],
         ),
+        globs_to_regex_params(
+            ["*c/foo"], case_insensitive=False, partial=True,
+            matches=["abc/foo/hi.py"],
+            nomatches=["abc/xfoo/hi.py", "foo/hi.py", "def/abc/foo/hi.py"],
+        ),
+        globs_to_regex_params(
+            ["foo/x*"], case_insensitive=False, partial=True,
+            matches=["foo/x", "foo/xhi.py", "foo/x/hi.py"],
+            nomatches=[],
+        ),
+        globs_to_regex_params(
+            ["foo/x*"], case_insensitive=False, partial=False,
+            matches=["foo/x", "foo/xhi.py"],
+            nomatches=["foo/x/hi.py"],
+        ),
         globs_to_regex_params(
             ["**/foo"],
             matches=["foo", "hello/foo", "hi/there/foo"],