Make core git URL rules explicit; support plain SCP-style git URLs as explicit VCS matches; update docs, tests, and create_project overloads

Author: tony

docs/url/registry.md

@@ -12,7 +12,7 @@ Detect VCS from `git`, `hg`, and `svn` URLs.
 [ParserMatch(vcs='git', match=GitURL(...))]
 
 >>> registry.match('git@invent.kde.org:plasma/plasma-sdk.git', is_explicit=True)
-[]
+[ParserMatch(vcs='git', match=GitURL(...))]
 
 >>> registry.match('git+ssh://git@invent.kde.org:plasma/plasma-sdk.git')
 [ParserMatch(vcs='git', match=GitURL(...))]

src/libvcs/_internal/shortcuts.py

@@ -68,6 +68,17 @@ def create_project(
 ) -> HgSync: ...
 
 
+@t.overload
+def create_project(
+    *,
+    url: str,
+    path: StrPath,
+    vcs: None = None,
+    progress_callback: ProgressCallbackProtocol | None = None,
+    **kwargs: dict[t.Any, t.Any],
+) -> GitSync | HgSync | SvnSync: ...
+
+
 def create_project(
     *,
     url: str,
@@ -98,6 +109,15 @@ def create_project(
     ...     path=tmp_path
     ... )
 
+    >>> isinstance(r, GitSync)
+    True
+
+    It also supports unprefixed SSH-style Git URLs:
+
+    >>> r = create_project(
+    ...     url='git@github.com:tmux-python/tmuxp.git',
+    ...     path=tmp_path
+    ... )
     >>> isinstance(r, GitSync)
     True
     """

src/libvcs/url/git.py

@@ -61,6 +61,7 @@
         """,
             re.VERBOSE,
         ),
+        is_explicit=True,
     ),
     # ends with .git. Including ones starting with https://
     # e.g. https://github.com/vcs-python/libvcs.git
@@ -77,6 +78,7 @@
             re.VERBOSE,
         ),
         defaults={"username": "git"},
+        is_explicit=True,
     ),
     # SCP-style URLs, e.g. git@
 ]
@@ -392,7 +394,7 @@ def is_valid(cls, url: str, is_explicit: bool | None = None) -> bool:
         >>> GitBaseURL.is_valid(
         ...     url='git@github.com:vcs-python/libvcs.git', is_explicit=True
         ... )
-        False
+        True
 
         In this case, check :meth:`GitPipURL.is_valid` or :meth:`GitURL.is_valid`'s
         examples.
@@ -764,7 +766,7 @@ def is_valid(cls, url: str, is_explicit: bool | None = None) -> bool:
         >>> GitURL.is_valid(
         ...     url='git@github.com:vcs-python/libvcs.git', is_explicit=True
         ... )
-        False
+        True
 
         You could create a GitHub rule that consider github.com hostnames to be
         exclusively git:

tests/test_shortcuts.py

@@ -70,3 +70,11 @@ def test_create_project(
     else:
         repo = create_project(**repo_dict)
         assert isinstance(repo, repo_class)
+
+
+def test_create_project_infer_scp_git(tmp_path: pathlib.Path) -> None:
+    """Test create_project infers Git VCS for SCP-style URLs."""
+    url = "git@github.com:tmux-python/tmuxp.git"
+    path = tmp_path / "tmuxp_repo"
+    repo = create_project(url=url, path=path)
+    assert isinstance(repo, GitSync)

tests/url/test_registry.py

@@ -53,6 +53,8 @@ class DetectVCSFixture(t.NamedTuple):
             "codecommit::ap-northeast-1://MyDemoRepo",
             "https://git-codecommit.us-east-1.amazonaws.com/v1/repos/test",
             "ssh://git-codecommit.us-east-1.amazonaws.com/v1/repos/test",
+            # plain SCP-style Git URLs should be recognized explicitly
+            "git@github.com:tmux-python/tmuxp.git",
         ]
     ],
     *[