roadmap-cli 0.1.1__py3-none-any.whl

roadmap/infrastructure/validation/file_enumeration.py

@@ -0,0 +1,219 @@
+"""Service for consistent file enumeration and parsing.
+
+Consolidates repeated patterns from services:
+- Directory walking with rglob("*.md")
+- Backup file filtering
+- Consistent error handling and logging
+- File-to-object parsing with retry logic
+
+This service eliminates ~200 lines of duplicated enumeration logic
+across IssueService, MilestoneService, ProjectService, and validators.
+
+Usage:
+
+    # Simple enumeration and parsing
+    issues = FileEnumerationService.enumerate_and_parse(
+        directory=issues_dir,
+        parser_func=IssueParser.parse_issue_file
+    )
+
+    # Enumeration with filtering
+    open_issues = FileEnumerationService.enumerate_with_filter(
+        directory=issues_dir,
+        parser_func=IssueParser.parse_issue_file,
+        filter_func=lambda issue: issue.status == Status.OPEN
+    )
+
+    # Find single item by ID
+    issue = FileEnumerationService.find_by_id(
+        directory=issues_dir,
+        id_value="abc12345",
+        parser_func=IssueParser.parse_issue_file
+    )
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from roadmap.common.errors.error_standards import OperationType, safe_operation
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class FileEnumerationService:
+    """Unified service for enumerating and filtering markdown files.
+
+    Provides consistent patterns for:
+    - Walking directories recursively
+    - Filtering backup files
+    - Parsing files with error handling
+    - Finding items by ID pattern
+    """
+
+    @staticmethod
+    @safe_operation(OperationType.READ, "File")
+    def enumerate_and_parse(
+        directory: Path,
+        parser_func: Callable[[Path], Any],
+        backup_filter: bool = True,
+        warn_on_parse_error: bool = False,
+    ) -> list[Any]:
+        """Enumerate files and parse with consistent error handling.
+
+        Args:
+            directory: Directory to enumerate
+            parser_func: Parser function (e.g., IssueParser.parse_issue_file)
+            backup_filter: Skip .backup files if True
+            warn_on_parse_error: If True, emit WARNING instead of DEBUG when a
+                file fails to parse. Use for entity types where a silent skip
+                would cause confusing inconsistencies (e.g., milestones).
+
+        Returns:
+            List of parsed objects (failed items skipped with logging)
+        """
+        logger.info("enumerate_and_parse_start", directory=str(directory))
+        if not directory.exists():
+            logger.debug(
+                "enumerate_and_parse_skip",
+                reason="directory_not_found",
+                directory=str(directory),
+            )
+            return []
+
+        results = []
+        # Use rglob to recursively search subdirectories (e.g., issues organized by milestone)
+        for file_path in directory.rglob("*.md"):
+            # Filter backup files if requested
+            if backup_filter and ".backup" in file_path.name:
+                continue
+
+            try:
+                obj = parser_func(file_path)
+                # Preserve the file path on the object for later updates
+                if obj is not None:
+                    try:
+                        obj.file_path = str(file_path)
+                    except (AttributeError, TypeError):
+                        # Object doesn't support attribute assignment (e.g., dict)
+                        # This can happen in tests with mocks
+                        pass
+                    results.append(obj)
+            except Exception as e:
+                log_event = "enumerate_and_parse_skip_file"
+                log_kwargs = {
+                    "file": str(file_path),
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                }
+                if warn_on_parse_error:
+                    logger.warning(log_event, **log_kwargs)
+                else:
+                    logger.debug(log_event, **log_kwargs)
+                continue
+
+        logger.debug(
+            "enumerate_and_parse_complete",
+            directory=str(directory),
+            count=len(results),
+        )
+        return results
+
+    @staticmethod
+    @safe_operation(OperationType.READ, "File")
+    def enumerate_with_filter(
+        directory: Path,
+        parser_func: Callable[[Path], Any],
+        filter_func: Callable[[Any], bool],
+        warn_on_parse_error: bool = False,
+    ) -> list[Any]:
+        """Enumerate, parse, and apply filter predicate.
+
+        Args:
+            directory: Directory to enumerate
+            parser_func: Parser function (e.g., IssueParser.parse_issue_file)
+            filter_func: Predicate function (return True to include)
+            warn_on_parse_error: Passed through to enumerate_and_parse.
+
+        Returns:
+            List of parsed and filtered objects
+        """
+        logger.info(
+            "enumerate_with_filter_start",
+            directory=str(directory),
+        )
+        items = FileEnumerationService.enumerate_and_parse(
+            directory, parser_func, warn_on_parse_error=warn_on_parse_error
+        )
+        filtered = [item for item in items if filter_func(item)]
+
+        logger.debug(
+            "enumerate_with_filter_complete",
+            directory=str(directory),
+            total=len(items),
+            filtered=len(filtered),
+        )
+        return filtered
+
+    @staticmethod
+    @safe_operation(OperationType.READ, "File")
+    def find_by_id(
+        directory: Path,
+        id_value: str,
+        parser_func: Callable[[Path], Any],
+    ) -> Any | None:
+        """Find a single file by ID pattern.
+
+        Searches for files matching pattern: {id_value}-*.md
+        Returns first match or None if not found.
+
+        Args:
+            directory: Directory to search
+            id_value: ID to search for (first 8 chars, e.g., "abc12345")
+            parser_func: Parser function
+
+        Returns:
+            First matching object or None
+        """
+        logger.info("find_by_id_start", id=id_value, directory=str(directory))
+        if not directory.exists():
+            logger.debug(
+                "find_by_id_skip",
+                reason="directory_not_found",
+                id=id_value,
+            )
+            return None
+
+        pattern = f"{id_value}-*.md"
+        for file_path in directory.rglob(pattern):
+            try:
+                obj = parser_func(file_path)
+                # Preserve the file path on the object for later updates
+                if obj is not None:
+                    try:
+                        obj.file_path = str(file_path)
+                    except (AttributeError, TypeError):
+                        # Object doesn't support attribute assignment
+                        pass
+                logger.debug(
+                    "find_by_id_found",
+                    id=id_value,
+                    file=file_path.name,
+                )
+                return obj
+            except Exception as e:
+                logger.debug(
+                    "find_by_id_parse_failed",
+                    id=id_value,
+                    file=file_path.name,
+                    error=str(e),
+                )
+                continue
+
+        logger.debug(
+            "find_by_id_not_found",
+            id=id_value,
+            directory=str(directory),
+        )
+        return None

roadmap/infrastructure/validation/github_assignee_validator.py

@@ -0,0 +1,47 @@
+"""GitHub-specific assignee validator implementation.
+
+Validates assignees against GitHub repository collaborators and
+provides canonical name resolution.
+"""
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class GitHubAssigneeValidator:
+    """Validates assignees against GitHub repository configuration.
+
+    Delegates to GitHubIntegrationService for the actual validation logic,
+    while implementing the AssigneeValidator protocol.
+    """
+
+    def __init__(self, github_service):
+        """Initialize with a GitHub integration service.
+
+        Args:
+            github_service: GitHubIntegrationService instance for validation
+        """
+        self.github_service = github_service
+
+    def validate(self, assignee: str) -> tuple[bool, str]:
+        """Validate assignee against GitHub.
+
+        Args:
+            assignee: Username to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        return self.github_service.validate_assignee(assignee)
+
+    def get_canonical_assignee(self, assignee: str) -> str:
+        """Get the canonical form of an assignee name from GitHub.
+
+        Args:
+            assignee: Input assignee name
+
+        Returns:
+            Canonical assignee name
+        """
+        return self.github_service.get_canonical_assignee(assignee)

roadmap/infrastructure/validation/github_validator.py

@@ -0,0 +1,101 @@
+"""GitHub-specific assignee validation implementation.
+
+Provides concrete GitHub-based validator implementation without coupling
+core services directly to GitHub adapter.
+"""
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.issue.assignee_validation_service import (
+    AssigneeValidationResult,
+)
+from roadmap.infrastructure.validation_gateway import ValidationGateway
+
+logger = get_logger(__name__)
+
+
+class GitHubAssigneeValidator:
+    """Validates assignees against GitHub repository access.
+
+    This is the infrastructure implementation that can be injected
+    into core validation services.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        owner: str,
+        repo: str,
+        cached_members: set[str] | list[str] | None = None,
+    ):
+        """Initialize with GitHub configuration.
+
+        Args:
+            token: GitHub API token
+            owner: Repository owner
+            repo: Repository name
+            cached_members: Optional cached team members for performance
+        """
+        self.token = token
+        self.owner = owner
+        self.repo = repo
+        self.cached_members = (
+            set(cached_members)
+            if isinstance(cached_members, list)
+            else (cached_members or set())
+        )
+
+    def validate(self, assignee: str) -> AssigneeValidationResult:
+        """Validate assignee against GitHub repository.
+
+        Args:
+            assignee: Username to validate
+
+        Returns:
+            AssigneeValidationResult with validation status
+        """
+        # Check cache first
+        if self.cached_members and assignee in self.cached_members:
+            return AssigneeValidationResult(is_valid=True, canonical_id=assignee)
+
+        # Do full validation via API
+        try:
+            client = ValidationGateway.get_github_client(
+                token=self.token, org=self.owner
+            )
+            github_valid, github_error = client.validate_assignee(assignee)  # type: ignore[attr-defined]
+
+            if github_valid:
+                return AssigneeValidationResult(is_valid=True, canonical_id=assignee)
+            else:
+                return AssigneeValidationResult(is_valid=False, message=github_error)
+
+        except Exception as e:
+            error_msg = f"GitHub validation failed: {e}"
+            logger.warning(
+                "github_validation_error",
+                assignee=assignee,
+                error=str(e),
+                severity="infrastructure",
+            )
+            return AssigneeValidationResult(is_valid=False, message=error_msg)
+
+    def get_team_members(self) -> list[str]:
+        """Get list of valid team members from GitHub.
+
+        Returns:
+            List of GitHub repository team members
+        """
+        try:
+            client = ValidationGateway.get_github_client(
+                token=self.token, org=self.owner
+            )
+            members = client.get_team_members()  # type: ignore[attr-defined]
+            logger.debug("github_team_members_retrieved", count=len(members))
+            return members
+        except Exception as e:
+            logger.warning(
+                "github_team_members_retrieval_failed",
+                error=str(e),
+                severity="infrastructure",
+            )
+            return []

roadmap/infrastructure/validation/milestone_consistency_validator.py

@@ -0,0 +1,96 @@
+"""Milestone Consistency Validation Module.
+
+Handles validation and fixing of milestone filename and name field consistency.
+Extracted from RoadmapCore to reduce god object complexity.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from roadmap.infrastructure.validation_gateway import ValidationGateway
+
+
+class MilestoneConsistencyValidator:
+    """Validates and fixes milestone naming consistency."""
+
+    def __init__(self, milestones_dir: Path):
+        """Initialize validator with milestones directory.
+
+        Args:
+            milestones_dir: Path to milestones directory
+        """
+        self.milestones_dir = milestones_dir
+
+    def validate(self) -> list[dict[str, str]]:
+        """Check for inconsistencies between milestone filenames and name fields.
+
+        Returns:
+            List of dictionaries with inconsistency details
+        """
+        inconsistencies = []
+
+        for milestone_file in sorted(self.milestones_dir.rglob("*.md"), key=str):
+            try:
+                milestone = ValidationGateway.parse_milestone_for_validation(
+                    milestone_file
+                )
+                expected_filename = milestone.filename
+                actual_filename = milestone_file.name
+
+                if expected_filename != actual_filename:
+                    inconsistencies.append(
+                        {
+                            "file": actual_filename,
+                            "name": milestone.name,
+                            "expected_filename": expected_filename,
+                            "type": "filename_mismatch",
+                        }
+                    )
+            except Exception as e:
+                inconsistencies.append(
+                    {
+                        "file": milestone_file.name,
+                        "name": "PARSE_ERROR",
+                        "expected_filename": "N/A",
+                        "type": "parse_error",
+                        "error": str(e),
+                    }
+                )
+
+        return inconsistencies
+
+    def fix(self) -> dict[str, list[str]]:
+        """Fix milestone filename inconsistencies by renaming files to match name fields.
+
+        Returns:
+            Dictionary with 'renamed' and 'errors' lists
+        """
+        results = {"renamed": [], "errors": []}
+        inconsistencies = self.validate()
+
+        for issue in inconsistencies:
+            if issue["type"] == "filename_mismatch":
+                old_path = self.milestones_dir / issue["file"]
+                new_path = self.milestones_dir / issue["expected_filename"]
+
+                try:
+                    # Check if target filename already exists
+                    if new_path.exists():
+                        results["errors"].append(
+                            f"Cannot rename {issue['file']} -> {issue['expected_filename']}: target exists"
+                        )
+                        continue
+
+                    old_path.rename(new_path)
+                    results["renamed"].append(
+                        f"{issue['file']} -> {issue['expected_filename']}"
+                    )
+                except Exception as e:
+                    results["errors"].append(
+                        f"Failed to rename {issue['file']}: {str(e)}"
+                    )
+            else:
+                results["errors"].append(f"Cannot fix {issue['file']}: {issue['type']}")
+
+        return results

roadmap/infrastructure/validation/vanilla_assignee_validator.py

@@ -0,0 +1,37 @@
+"""Vanilla/Git assignee validator for git sync backend.
+
+Used when the sync backend is vanilla/git, this validator accepts
+any assignee without validation since there's no centralized user registry.
+"""
+
+
+class VanillaAssigneeValidator:
+    """Validator that accepts any assignee without validation.
+
+    Used for git/vanilla sync backend where there's no centralized
+    user registry to validate against.
+    """
+
+    def validate(self, assignee: str) -> tuple[bool, str]:
+        """Accept any non-empty assignee without validation.
+
+        Args:
+            assignee: Username to validate
+
+        Returns:
+            (True, "") if assignee is non-empty, otherwise (False, error message)
+        """
+        if not assignee or not assignee.strip():
+            return False, "Assignee cannot be empty"
+        return True, ""
+
+    def get_canonical_assignee(self, assignee: str) -> str:
+        """Return the assignee as-is (no mapping).
+
+        Args:
+            assignee: Input assignee name
+
+        Returns:
+            Same assignee name unchanged
+        """
+        return assignee

roadmap/infrastructure/validation_gateway.py

@@ -0,0 +1,96 @@
+"""Gateway to validation infrastructure adapter access for core services.
+
+This module mediates core service access to validation-related adapters,
+ensuring proper layer separation between Core and Infrastructure.
+
+All imports from roadmap.adapters accessed via validation are localized here.
+Core services use this gateway instead of importing validation modules directly
+or accessing adapters through validation.
+"""
+
+import os
+from typing import Any
+
+
+class _NullGitHubClient:
+    """Fallback client for validation when no GitHub token is configured."""
+
+    def validate_assignee(self, assignee: str) -> tuple[bool, str]:
+        return False, "GitHub token not configured"
+
+    def get_team_members(self) -> list[str]:
+        return []
+
+
+class ValidationGateway:
+    """Gateway for validation operations.
+
+    Provides a centralized interface for core services to access validation
+    functionality that internally uses adapters (GitHub, persistence parsers, etc.)
+    without direct adapter imports in core.
+    """
+
+    @staticmethod
+    def get_github_client(token: str | None = None, org: str | None = None) -> Any:
+        """Get GitHub API client for validation operations.
+
+        Args:
+            token: GitHub API token (optional)
+            org: GitHub organization (optional)
+
+        Returns:
+            GitHub client instance from adapters
+        """
+        from roadmap.adapters.github.github import GitHubClient
+        from roadmap.infrastructure.security.credentials import get_credential_manager
+
+        resolved_token = token or os.getenv("GITHUB_TOKEN")
+        if not resolved_token:
+            try:
+                resolved_token = get_credential_manager().get_token()
+            except Exception:
+                resolved_token = None
+
+        if not resolved_token:
+            return _NullGitHubClient()
+
+        return GitHubClient(token=resolved_token, owner=org)
+
+    @staticmethod
+    def parse_issue_for_validation(file_path: Any) -> Any:
+        """Parse issue from file for validation.
+
+        Args:
+            file_path: Path to issue file
+
+        Returns:
+            Parsed Issue object
+        """
+        from roadmap.adapters.persistence.parser import IssueParser
+
+        return IssueParser.parse_issue_file(file_path)
+
+    @staticmethod
+    def parse_milestone_for_validation(file_path: Any) -> Any:
+        """Parse milestone from file for validation.
+
+        Args:
+            file_path: Path to milestone file
+
+        Returns:
+            Parsed Milestone object
+        """
+        from roadmap.adapters.persistence.parser import MilestoneParser
+
+        return MilestoneParser.parse_milestone_file(file_path)
+
+    @staticmethod
+    def get_parser_module() -> Any:
+        """Get the parser module for custom parsing operations.
+
+        Returns:
+            Parser module from adapters
+        """
+        from roadmap.adapters.persistence import parser
+
+        return parser