refactor: replace SubProject inheritance with has-a Fetcher composition

AGENTS.md

@@ -71,7 +71,7 @@ dfetch.log          ← logging (lowest layer)
 - **`dfetch/__main__.py`** — CLI entry point; builds argparse subcommands and dispatches
 - **`dfetch/commands/`** — One file per CLI command (e.g., `update.py`, `check.py`); all inherit from `command.py`'s abstract `Command` base
 - **`dfetch/manifest/`** — YAML manifest loading/writing with `strictyaml` schema validation; `manifest.py` is the main handler
-- **`dfetch/project/`** — Abstract `Subproject`/`Superproject` classes with concrete Git, SVN, and Archive implementations; factory functions `create_sub_project()` and `create_super_project()` are the main entry points
+- **`dfetch/project/`** — Concrete `SubProject` domain aggregate that composes with a `Fetcher`; `GitFetcher`, `SvnFetcher`, and `ArchiveFetcher` implement the `Fetcher`/`VcsFetcher` protocols defined in `fetcher.py`; factory functions `create_sub_project()` and `create_super_project()` are the main entry points
 - **`dfetch/vcs/`** — Low-level VCS operations: `git.py`, `svn.py`, `archive.py` (with hash verification in `integrity_hash.py`), and `patch.py`
 - **`dfetch/reporting/`** — Output formatters; check results can be emitted as stdout, Jenkins JSON, SARIF, or Code Climate format; SBOM output uses CycloneDX format
 - **`dfetch/terminal/`** — Terminal UI components (interactive prompts, tree browser, ANSI colors)
@@ -84,7 +84,7 @@ dfetch.log          ← logging (lowest layer)
 
 ### Adding a new VCS backend
 
-Implement the abstract interfaces in `dfetch/project/subproject.py` and `dfetch/vcs/` and register via the factory in `dfetch/project/`.
+Implement the `Fetcher` protocol (or `VcsFetcher` if you need branch/tag/revision semantics) defined in `dfetch/project/fetcher.py`, add a concrete class in `dfetch/project/`, add low-level VCS operations in `dfetch/vcs/` if needed, and register via the factory in `dfetch/project/__init__.py`.
 
 ## Testing conventions
 

dfetch/commands/add.py

@@ -29,10 +29,8 @@
 from dfetch.manifest.remote import Remote
 from dfetch.manifest.version import Version
 from dfetch.project import create_sub_project, create_super_project
-from dfetch.project.gitsubproject import GitSubProject
 from dfetch.project.subproject import SubProject
 from dfetch.project.superproject import SuperProject
-from dfetch.project.svnsubproject import SvnSubProject
 from dfetch.terminal import Entry, LsFunction
 from dfetch.terminal.tree_browser import (
     BrowserConfig,
@@ -86,9 +84,9 @@ def browse_tree(subproject: SubProject, version: str = "") -> Generator[LsFuncti
     Adds '.' as the first entry to allow selecting the repo root (which is
     treated as empty src).
     """
-    if isinstance(subproject, (GitSubProject, SvnSubProject)):
-        remote = subproject.remote_repo
-        with remote.browse_tree(version) as vcs_ls:
+    vcs = subproject.as_vcs()
+    if vcs is not None:
+        with vcs.browse_tree(version) as vcs_ls:
 
             def ls(path: str = "") -> list[Entry]:
                 entries = [
@@ -274,44 +272,54 @@ def _finalize_add(
         Update()(update_args)
 
 
+def _resolve_entry_version(ctx: _AddContext, raw_version: str) -> Version:
+    """Resolve a raw version string to a ``Version`` using remote branches and tags.
+
+    For archive-backed subprojects ``raw_version`` is preserved as a revision
+    identifier (URL or hash) because archives have no branch/tag semantics.
+    """
+    if ctx.subproject.as_vcs() is None:
+        return Version(revision=raw_version)
+    branches = ctx.subproject.list_of_branches()
+    tags = ctx.subproject.list_of_tags()
+    choices: list[Version] = [
+        *[Version(branch=b) for b in prioritise_default(branches, ctx.default_branch)],
+        *[Version(tag=t) for t in sort_tags_newest_first(tags)],
+    ]
+    return _resolve_raw_version(raw_version, choices) or Version(
+        branch=ctx.default_branch
+    )
+
+
 def _non_interactive_entry(ctx: _AddContext, overrides: _Overrides) -> ProjectEntry:
     """Build a ``ProjectEntry`` using inferred defaults (no user interaction)."""
-    if overrides.version:
-        branches = ctx.subproject.list_of_branches()
-        tags = ctx.subproject.list_of_tags()
-        choices: list[Version] = [
-            *[
-                Version(branch=b)
-                for b in prioritise_default(branches, ctx.default_branch)
-            ],
-            *[Version(tag=t) for t in sort_tags_newest_first(tags)],
-        ]
-        version = _resolve_raw_version(overrides.version, choices) or Version(
-            branch=ctx.default_branch
-        )
-    else:
-        version = Version(branch=ctx.default_branch)
+    version = (
+        _resolve_entry_version(ctx, overrides.version)
+        if overrides.version
+        else Version(branch=ctx.default_branch)
+    )
     existing_names = {p.name for p in ctx.manifest.projects}
-    return _build_entry(
+    entry = _build_entry(
         name=overrides.name or _unique_name(ctx.default_name, existing_names),
         remote_url=ctx.url,
         dst=overrides.dst or ctx.default_dst,
         version=version,
         src=overrides.src or "",
         ignore=overrides.ignore or [],
-        remote_to_use=ctx.remote_to_use,
     )
+    if ctx.remote_to_use:
+        entry.set_remote(ctx.remote_to_use)
+    return entry
 
 
-def _build_entry(  # pylint: disable=too-many-arguments
+def _build_entry(
     *,
     name: str,
     remote_url: str,
     dst: str,
     version: Version,
     src: str,
     ignore: list[str],
-    remote_to_use: Remote | None,
 ) -> ProjectEntry:
     """Assemble a ``ProjectEntry`` from the fields collected by the wizard."""
     kind, value = version.field
@@ -325,10 +333,7 @@ def _build_entry(  # pylint: disable=too-many-arguments
         entry_dict["src"] = src
     if ignore:
         entry_dict["ignore"] = ignore
-    entry = ProjectEntry(entry_dict)
-    if remote_to_use:
-        entry.set_remote(remote_to_use)
-    return entry
+    return ProjectEntry(entry_dict)
 
 
 # ---------------------------------------------------------------------------
@@ -340,15 +345,17 @@ def _show_url_fields(
     name: str, remote_url: str, default_branch: str, remote_to_use: Remote | None
 ) -> None:
     """Print the fields determined solely by the URL (name, remote, url, repo-path)."""
-    seed = _build_entry(
+    entry = _build_entry(
         name=name,
         remote_url=remote_url,
         dst=name,
         version=Version(branch=default_branch),
         src="",
         ignore=[],
-        remote_to_use=remote_to_use,
-    ).as_yaml()
+    )
+    if remote_to_use:
+        entry.set_remote(remote_to_use)
+    seed = entry.as_yaml()
     logger.print_yaml(
         {k: seed[k] for k in ("name", "remote", "url", "repo-path") if k in seed}
     )
@@ -414,15 +421,17 @@ def _interactive_flow(ctx: _AddContext, overrides: _Overrides) -> ProjectEntry:
 
     src, ignore = _pick_src_and_ignore(ctx.subproject, version_value, overrides)
 
-    return _build_entry(
+    entry = _build_entry(
         name=name,
         remote_url=ctx.url,
         dst=dst,
         version=version,
         src=src,
         ignore=ignore,
-        remote_to_use=ctx.remote_to_use,
     )
+    if ctx.remote_to_use:
+        entry.set_remote(ctx.remote_to_use)
+    return entry
 
 
 # ---------------------------------------------------------------------------
@@ -507,10 +516,12 @@ def _ask_src(ls_function: LsFunction) -> str:
         src = tree_single_pick(ls_function, "Source path", dirs_selectable=True)
         return "" if src == "." else src
 
-    return Prompt.ask(
-        _PROMPT_FORMAT.format(label="Source path")
-        + "  (sub-path/glob, or Enter to fetch whole repo)",
-        default="",
+    return str(
+        Prompt.ask(
+            _PROMPT_FORMAT.format(label="Source path")
+            + "  (sub-path/glob, or Enter to fetch whole repo)",
+            default="",
+        )
     ).strip()
 
 

dfetch/commands/environment.py

@@ -16,7 +16,7 @@
 
 import dfetch.commands.command
 from dfetch.log import get_logger
-from dfetch.project import SUPPORTED_SUBPROJECT_TYPES
+from dfetch.project import SUPPORTED_FETCHERS
 
 logger = get_logger(__name__)
 
@@ -37,5 +37,5 @@ def __call__(self, _: argparse.Namespace) -> None:
         logger.print_report_line(
             "platform", f"{platform.system()} {platform.release()}"
         )
-        for project_type in SUPPORTED_SUBPROJECT_TYPES:
-            project_type.list_tool_info()
+        for fetcher_type in SUPPORTED_FETCHERS:
+            fetcher_type.list_tool_info()

dfetch/commands/format_patch.py

@@ -34,9 +34,7 @@
 import dfetch.project
 from dfetch.log import get_logger
 from dfetch.project import create_super_project
-from dfetch.project.gitsubproject import GitSubProject
 from dfetch.project.subproject import SubProject
-from dfetch.project.svnsubproject import SvnSubProject
 from dfetch.util.util import (
     catch_runtime_exceptions,
     check_no_path_traversal,
@@ -145,12 +143,6 @@ def __call__(self, args: argparse.Namespace) -> None:
 
 
 def _determine_target_patch_type(subproject: SubProject) -> PatchType:
-    """Determine the subproject type for the patch."""
-    if isinstance(subproject, GitSubProject):
-        required_type = PatchType.GIT
-    elif isinstance(subproject, SvnSubProject):
-        required_type = PatchType.SVN
-    else:
-        required_type = PatchType.PLAIN
-
-    return required_type
+    """Determine the patch format for *subproject*."""
+    vcs = subproject.as_vcs()
+    return vcs.patch_type() if vcs is not None else PatchType.PLAIN

dfetch/log.py

@@ -17,15 +17,22 @@
 from dfetch import __version__
 
 
-class _NoExpandLogRender(LogRender):  # pylint: disable=too-few-public-methods
-    """LogRender that disables table expansion to prevent blank lines in asciicasts."""
+def _make_non_expanding_log_render(**kwargs: Any) -> Any:
+    """Return a LogRender callable that disables table expansion.
 
-    def __call__(self, *args: Any, **kwargs: Any) -> Any:
-        """Render log entry without expanding the table to the full terminal width."""
-        table = super().__call__(*args, **kwargs)
+    Used when recording with asciinema to prevent Rich's ``expand=True`` from
+    padding log lines to the full terminal width, which produces spurious blank
+    lines in the cast player.
+    """
+    renderer = LogRender(**kwargs)
+
+    def _render(*args: Any, **kw: Any) -> Any:
+        table = renderer(*args, **kw)
         table.expand = False
         return table
 
+    return _render
+
 
 def make_console(no_color: bool = False) -> Console:
     """Create a Rich Console with proper color handling."""
@@ -57,9 +64,10 @@ def configure_root_logger(console: Console | None = None) -> None:
         # causing the subsequent newline to produce a blank line in the cast
         # player.  Wrapping _log_render so it returns a non-expanding table
         # removes the trailing spaces and avoids the spurious blank lines.
-        handler._log_render = _NoExpandLogRender(  # pylint: disable=protected-access
+        no_expand = _make_non_expanding_log_render(
             show_time=False, show_level=False, show_path=False
         )
+        handler._log_render = no_expand  # pylint: disable=protected-access
 
     logging.basicConfig(
         level=logging.INFO,

dfetch/project/__init__.py

@@ -7,37 +7,38 @@
 from dfetch.log import get_logger
 from dfetch.manifest.manifest import Manifest
 from dfetch.manifest.parse import find_manifest
-from dfetch.project.archivesubproject import ArchiveSubProject
-from dfetch.project.gitsubproject import GitSubProject
+from dfetch.project.archivesubproject import ArchiveFetcher
+from dfetch.project.gitsubproject import GitFetcher
 from dfetch.project.gitsuperproject import GitSuperProject
 from dfetch.project.subproject import SubProject
 from dfetch.project.superproject import NoVcsSuperProject, SuperProject
-from dfetch.project.svnsubproject import SvnSubProject
+from dfetch.project.svnsubproject import SvnFetcher
 from dfetch.project.svnsuperproject import SvnSuperProject
 from dfetch.util.util import resolve_absolute_path
 
-SUPPORTED_SUBPROJECT_TYPES: list[
-    type[ArchiveSubProject] | type[GitSubProject] | type[SvnSubProject]
-] = [ArchiveSubProject, GitSubProject, SvnSubProject]
+_AnyFetcherType = type[ArchiveFetcher] | type[GitFetcher] | type[SvnFetcher]
+SUPPORTED_FETCHERS: list[_AnyFetcherType] = [ArchiveFetcher, GitFetcher, SvnFetcher]
 SUPPORTED_SUPERPROJECT_TYPES = [GitSuperProject, SvnSuperProject]
 
+# Backward-compatible alias used by environment.py and any external callers.
+SUPPORTED_SUBPROJECT_TYPES = SUPPORTED_FETCHERS
+
 logger = get_logger(__name__)
 
 
 def create_sub_project(
     project_entry: dfetch.manifest.project.ProjectEntry,
 ) -> SubProject:
-    """Create a new SubProject based on a project from the manifest."""
-    for project_type in SUPPORTED_SUBPROJECT_TYPES:
-        if project_type.NAME == project_entry.vcs:
-            return project_type(project_entry)
+    """Create a SubProject by selecting the appropriate fetcher for *project_entry*."""
+    for fetcher_type in SUPPORTED_FETCHERS:
+        if fetcher_type.NAME == project_entry.vcs:
+            return SubProject(project_entry, fetcher_type(project_entry.remote_url))
 
-    for project_type in SUPPORTED_SUBPROJECT_TYPES:
-        project = project_type(project_entry)
+    for fetcher_type in SUPPORTED_FETCHERS:
+        if fetcher_type.handles(project_entry.remote_url):
+            return SubProject(project_entry, fetcher_type(project_entry.remote_url))
 
-        if project.check():
-            return project
-    raise RuntimeError("vcs type unsupported")
+    raise RuntimeError(f"vcs type unsupported for {project_entry.remote_url}")
 
 
 def create_super_project() -> SuperProject: