config(feat[models,loader]): Implement modern configuration system with Pydantic models

why: The legacy configuration system had complex handling spread across multiple files with
redundant validation, nested structures, and lacking formal schema. This modernization
simplifies the configuration format, enhances type safety, and improves maintainability.

what:
- Replaced nested YAML structure with flatter, more consistent format
- Implemented Pydantic v2 models for configuration (Repository, Settings, VCSPullConfig)
- Created comprehensive validation logic including path normalization
- Developed configuration loading functions with TypeAdapter for optimized validation
- Implemented include resolution logic for configuration composition
- Added consistent path handling and file resolution utilities
- Created VCS interface and implementations for Git, Mercurial, and SVN
- Implemented CLI commands for info and sync operations
- Restructured test organization to mirror source code
- Added comprehensive unit tests for models and loader
- Created example configuration and API usage demonstrations
- Fixed all type errors and linting issues

refs: Addresses items in notes/TODO.md, specifically sections 1 (Configuration Format & Structure),
2 (Validation System), and portions of 3 (Testing System) and 4 (Internal APIs).
See also: notes/proposals/01-config-format-structure.md

Author: tony

examples/api_usage.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+"""Example script demonstrating VCSPull API usage."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Add the parent directory to the path so we can import vcspull
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from vcspull import load_config
+from vcspull.config import resolve_includes
+from vcspull.vcs import get_vcs_handler
+
+
+def main() -> int:
+    """Main function."""
+    # Load configuration
+    config_path = Path(__file__).parent / "vcspull.yaml"
+
+    if not config_path.exists():
+        print(f"Configuration file not found: {config_path}")
+        return 1
+
+    print(f"Loading configuration from {config_path}")
+    config = load_config(config_path)
+
+    # Resolve includes
+    config = resolve_includes(config, config_path.parent)
+
+    # Print settings
+    print("\nSettings:")
+    print(f"  sync_remotes: {config.settings.sync_remotes}")
+    print(f"  default_vcs: {config.settings.default_vcs}")
+    print(f"  depth: {config.settings.depth}")
+
+    # Print repositories
+    print(f"\nRepositories ({len(config.repositories)}):")
+    for repo in config.repositories:
+        print(f"  {repo.name or 'unnamed'}:")
+        print(f"    url: {repo.url}")
+        print(f"    path: {repo.path}")
+        print(f"    vcs: {repo.vcs}")
+        if repo.rev:
+            print(f"    rev: {repo.rev}")
+        if repo.remotes:
+            print(f"    remotes: {repo.remotes}")
+
+    # Example of using VCS handlers
+    print("\nVCS Handler Example:")
+    if config.repositories:
+        repo = config.repositories[0]
+        handler = get_vcs_handler(repo, config.settings.default_vcs)
+
+        print(f"  Handler type: {type(handler).__name__}")
+        print(f"  Repository exists: {handler.exists()}")
+
+        # Clone the repository if it doesn't exist
+        if not handler.exists():
+            print(f"  Cloning repository {repo.name}...")
+            if handler.clone():
+                print("  Clone successful")
+            else:
+                print("  Clone failed")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/vcspull.yaml

@@ -0,0 +1,39 @@
+# Example VCSPull configuration file
+
+# Global settings
+settings:
+  sync_remotes: true
+  default_vcs: git
+  depth: 1
+
+# Repository definitions
+repositories:
+  # Git repositories
+  - name: vcspull
+    url: https://github.com/vcs-python/vcspull.git
+    path: ~/code/vcspull
+    vcs: git
+    rev: main
+  
+  - name: libvcs
+    url: https://github.com/vcs-python/libvcs.git
+    path: ~/code/libvcs
+    vcs: git
+    remotes:
+      upstream: https://github.com/vcs-python/libvcs.git
+  
+  # Mercurial repository
+  - name: mercurial-repo
+    url: https://www.mercurial-scm.org/repo/hello
+    path: ~/code/mercurial-hello
+    vcs: hg
+  
+  # Subversion repository
+  - name: svn-repo
+    url: https://svn.apache.org/repos/asf/subversion/trunk
+    path: ~/code/svn-trunk
+    vcs: svn
+
+# Include other configuration files
+includes:
+  - ~/more-repos.yaml 

src/vcspull/README.md

@@ -0,0 +1,143 @@
+# VCSPull Package Structure
+
+This document outlines the structure of the modernized VCSPull package.
+
+## Directory Structure
+
+```
+src/vcspull/
+├── __about__.py       # Package metadata
+├── __init__.py        # Package initialization
+├── _internal/         # Internal utilities
+│   ├── __init__.py
+│   └── logger.py      # Logging utilities
+├── cli/               # Command-line interface
+│   ├── __init__.py
+│   └── commands.py    # CLI command implementations
+├── config/            # Configuration handling
+│   ├── __init__.py
+│   ├── loader.py      # Configuration loading functions
+│   └── models.py      # Configuration models
+└── vcs/               # Version control system interfaces
+    ├── __init__.py
+    ├── base.py        # Base VCS interface
+    ├── git.py         # Git implementation
+    ├── mercurial.py   # Mercurial implementation
+    └── svn.py         # Subversion implementation
+```
+
+## Module Responsibilities
+
+### Configuration (`config/`)
+
+- **models.py**: Defines Pydantic models for configuration
+- **loader.py**: Provides functions for loading and resolving configuration files
+
+### Version Control Systems (`vcs/`)
+
+- **base.py**: Defines the abstract interface for VCS operations
+- **git.py**, **mercurial.py**, **svn.py**: Implementations for specific VCS types
+
+### Command-line Interface (`cli/`)
+
+- **commands.py**: Implements CLI commands and argument parsing
+
+### Internal Utilities (`_internal/`)
+
+- **logger.py**: Logging utilities for the package
+
+## Configuration Format
+
+VCSPull uses a YAML or JSON configuration format with the following structure:
+
+```yaml
+settings:
+  sync_remotes: true
+  default_vcs: git
+  depth: 1
+
+repositories:
+  - name: example-repo
+    url: https://github.com/user/repo.git
+    path: ~/code/repo
+    vcs: git
+    rev: main
+    remotes:
+      upstream: https://github.com/upstream/repo.git
+    web_url: https://github.com/user/repo
+
+includes:
+  - ~/other-config.yaml
+```
+
+## Usage
+
+```python
+from vcspull import load_config
+
+# Load configuration
+config = load_config("~/.config/vcspull/vcspull.yaml")
+
+# Access repositories
+for repo in config.repositories:
+    print(f"{repo.name}: {repo.url} -> {repo.path}")
+```
+
+## Implemented Features
+
+The following features have been implemented according to the modernization plan:
+
+1. **Configuration Format & Structure**
+   - Defined Pydantic v2 models for configuration
+   - Implemented comprehensive validation logic
+   - Created configuration loading functions
+   - Added include resolution logic
+   - Implemented configuration merging functions
+
+2. **Validation System**
+   - Migrated all validation to Pydantic v2 models
+   - Used Pydantic's built-in validation capabilities
+   - Created clear type aliases
+   - Implemented path expansion and normalization
+
+3. **Testing System**
+   - Reorganized tests to mirror source code structure
+   - Created separate unit test directories
+   - Implemented test fixtures for configuration files
+
+4. **Internal APIs**
+   - Reorganized codebase according to proposed structure
+   - Separated public and private API components
+   - Created logical module organization
+   - Standardized function signatures
+   - Implemented clear parameter and return types
+   - Added comprehensive docstrings with type information
+
+5. **External APIs**
+   - Created dedicated API module
+   - Implemented load_config function
+   - Defined public interfaces
+
+6. **CLI System**
+   - Implemented basic CLI commands
+   - Added configuration handling in CLI
+   - Created command structure
+
+## Next Steps
+
+The following features are planned for future implementation:
+
+1. **VCS Operations**
+   - Implement full synchronization logic
+   - Add support for remote management
+   - Implement revision locking
+
+2. **CLI Enhancements**
+   - Add progress reporting
+   - Implement rich output formatting
+   - Add repository detection command
+
+3. **Documentation**
+   - Generate JSON schema documentation
+   - Create example configuration files
+   - Update user documentation with new format 

src/vcspull/__init__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 """Manage multiple git, mercurial, svn repositories from a YAML / JSON file.
 
-:copyright: Copyright 2013-2018 Tony Narlock.
+:copyright: Copyright 2013-2024 Tony Narlock.
 :license: MIT, see LICENSE for details
 """
 
@@ -12,5 +12,9 @@
 from logging import NullHandler
 
 from . import cli
+from .__about__ import __version__
+from .config import load_config
 
 logging.getLogger(__name__).addHandler(NullHandler())
+
+__all__ = ["__version__", "cli", "load_config"]

src/vcspull/_internal/__init__.py

@@ -0,0 +1,11 @@
+"""Internal utilities for VCSPull.
+
+This module contains internal utilities that should not be used directly
+by external code.
+"""
+
+from __future__ import annotations
+
+from .logger import logger
+
+__all__ = ["logger"]

src/vcspull/_internal/logger.py

@@ -0,0 +1,53 @@
+"""Logging utilities for VCSPull."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+# Create a logger for this package
+logger = logging.getLogger("vcspull")
+
+
+def setup_logger(
+    level: int | str = logging.INFO,
+    log_file: str | None = None,
+) -> None:
+    """Set up the logger with handlers.
+
+    Parameters
+    ----------
+    level : Union[int, str]
+        Logging level
+    log_file : Optional[str]
+        Path to log file
+    """
+    # Convert string level to int if needed
+    if isinstance(level, str):
+        level = getattr(logging, level.upper(), logging.INFO)
+
+    logger.setLevel(level)
+
+    # Remove existing handlers
+    for handler in logger.handlers:
+        logger.removeHandler(handler)
+
+    # Create console handler
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(level)
+
+    # Create formatter
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+    console_handler.setFormatter(formatter)
+
+    # Add console handler to logger
+    logger.addHandler(console_handler)
+
+    # Add file handler if log_file is provided
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(level)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)

src/vcspull/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface for VCSPull."""
+
+from __future__ import annotations
+
+from .commands import cli
+
+__all__ = ["cli"]