roadmap-cli 0.1.1__py3-none-any.whl

roadmap/common/logging/utils.py

@@ -0,0 +1,335 @@
+"""Logging setup and utility functions."""
+
+import logging
+import logging.config
+import logging.handlers
+import random
+import time
+import traceback
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from roadmap.common.logging.correlation import add_correlation_id
+from roadmap.common.logging.formatters import (
+    include_structured_fields_in_message,
+    scrub_sensitive_data,
+)
+from roadmap.common.observability.instrumentation import span_context_processor
+
+
+def setup_logging(
+    log_level: str = "INFO",
+    log_to_file: bool = True,
+    log_dir: str | Path | None = None,
+    debug_mode: bool = False,
+    console_level: str | None = None,
+    custom_levels: dict[str, str] | None = None,
+) -> structlog.stdlib.BoundLogger:
+    """Set up structured logging for the roadmap application.
+
+    Args:
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_to_file: Whether to log to file in addition to console
+        log_dir: Directory for log files (defaults to .roadmap/logs in current working directory)
+        debug_mode: Enable debug mode with verbose output
+        console_level: Override console handler level (e.g., "INFO" for --verbose)
+                      If None, defaults to DEBUG if debug_mode else WARNING
+        custom_levels: Dict of logger_name: level for per-component log levels
+
+    Returns:
+        Configured structlog logger
+    """
+    if log_dir is None:
+        log_dir = Path.cwd() / ".roadmap" / "logs"
+    else:
+        log_dir = Path(log_dir)
+
+    # Ensure log directory exists
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / "roadmap.log"
+
+    # Configure standard library logging
+    # Use explicit sys.stderr for console to ensure logs go to stderr, not stdout
+    # Determine console level: explicit override > debug_mode > default WARNING
+    if console_level is None:
+        console_level = "DEBUG" if debug_mode else "WARNING"
+
+    handlers: dict[str, Any] = {
+        "console": {
+            "class": "logging.StreamHandler",
+            "level": console_level,
+            "formatter": "console",
+            "stream": "ext://sys.stderr",  # Explicitly use stderr
+        }
+    }
+
+    formatters = {
+        "console": {
+            "format": "%(asctime)s [%(levelname)8s] %(name)s: %(message)s",
+            "datefmt": "%Y-%m-%dT%H:%M:%SZ",
+        }
+    }
+
+    if log_to_file:
+        handlers["file"] = {
+            "class": "logging.handlers.RotatingFileHandler",
+            "level": "DEBUG",
+            "formatter": "structured",
+            "filename": str(log_file),
+            "maxBytes": 10485760,  # 10MB
+            "backupCount": 5,
+            "encoding": "utf-8",
+        }
+
+        formatters["structured"] = {
+            "format": "%(asctime)s [%(levelname)8s] %(name)s: %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        }
+
+    # Build logger configuration with custom levels support
+    loggers_config = {
+        "roadmap": {
+            "level": log_level,
+            "handlers": list(handlers.keys()),
+            "propagate": False,
+        },
+        "roadmap.security": {
+            "level": "INFO",
+            "handlers": list(handlers.keys()),
+            "propagate": False,
+        },
+        # Suppress noisy third-party loggers
+        "urllib3": {"level": "WARNING"},
+        "requests": {"level": "WARNING"},
+        "aiohttp": {"level": "WARNING"},
+        "git": {"level": "WARNING"},
+    }
+
+    # Add custom per-component log levels
+    if custom_levels:
+        for logger_name, level in custom_levels.items():
+            full_name = (
+                f"roadmap.{logger_name}"
+                if not logger_name.startswith("roadmap.")
+                else logger_name
+            )
+            loggers_config[full_name] = {
+                "level": level.upper(),
+                "handlers": list(handlers.keys()),
+                "propagate": False,
+            }
+
+    config = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": formatters,
+        "handlers": handlers,
+        "loggers": loggers_config,
+        "root": {
+            "level": "WARNING",
+            "handlers": list(handlers.keys()),  # Use all configured handlers
+        },
+    }
+
+    logging.config.dictConfig(config)
+
+    # Configure structlog with enhanced processors
+    # Route through stdlib logging handlers (console → stderr, file → JSON)
+    processors: list = [
+        # Add correlation ID first (before any filtering)
+        add_correlation_id,
+        # Add span context for tracing
+        span_context_processor,
+        # Scrub sensitive data early in pipeline
+        scrub_sensitive_data,
+        # Add standard metadata
+        structlog.stdlib.add_log_level,
+        # NOTE: Do NOT use add_logger_name when using render_to_log_kwargs
+        # because it creates a "logger" key that becomes "name" kwarg in LogRecord,
+        # causing: KeyError: "Attempt to overwrite 'name' in LogRecord"
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        # Include structured fields in message for visibility
+        include_structured_fields_in_message,
+        # Convert to stdlib logging kwargs and pass through to handlers
+        structlog.stdlib.render_to_log_kwargs,
+    ]
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.stdlib.BoundLogger,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        context_class=dict,
+        cache_logger_on_first_use=True,
+    )
+
+    return structlog.get_logger("roadmap")
+
+
+def get_stack_trace(depth: int = 5) -> str:
+    """Get a formatted stack trace for DEBUG logging.
+
+    This utility makes it easy to add rich context to DEBUG logs without
+    cluttering the normal code path. Stack traces help with troubleshooting
+    unexpected behavior and finding where operations are triggered from.
+
+    Args:
+        depth: Number of stack frames to include (default 5)
+
+    Returns:
+        Formatted multi-line stack trace suitable for log output
+
+    Example:
+        logger = get_logger(__name__)
+        logger.debug(
+            "operation_triggered",
+            operation="sync",
+            stack=get_stack_trace()
+        )
+    """
+    stack_lines = traceback.format_stack()[:-1]  # Exclude this function
+    # Get the last 'depth' frames
+    relevant_lines = stack_lines[-depth:]
+    formatted = "\n  ".join([line.strip() for line in relevant_lines])
+    return formatted
+
+
+@contextmanager
+def log_operation_timing(operation: str, logger=None, **context):
+    """Context manager for timing and logging operations.
+
+    Args:
+        operation: Operation name
+        logger: Optional logger (uses default if None)
+        **context: Additional context to log
+
+    Usage:
+        with log_operation_timing("create_issue", issue_id="123"):
+            core.create_issue(...)
+
+    This will log:
+        - Starting {operation} with context
+        - Completed {operation} with duration and success status
+        - Failed {operation} with duration and error details (on exception)
+    """
+    from roadmap.common.logging.loggers import get_logger
+
+    logger = logger or get_logger()
+    start_time = time.perf_counter()
+
+    logger.info(
+        "operation_started",
+        operation=operation,
+        **context,
+    )
+
+    try:
+        yield
+        duration = time.perf_counter() - start_time
+        logger.info(
+            "operation_completed",
+            operation=operation,
+            duration_ms=round(duration * 1000, 2),
+            success=True,
+            **context,
+        )
+    except Exception as e:
+        duration = time.perf_counter() - start_time
+        logger.error(
+            "operation_failed",
+            operation=operation,
+            duration_ms=round(duration * 1000, 2),
+            success=False,
+            error_type=type(e).__name__,
+            error_message=str(e),
+            **context,
+        )
+        raise
+
+
+def log_operation(operation: str, **context):
+    """Log operation start/end with context and timing.
+
+    Args:
+        operation: Operation name
+        **context: Additional context to log
+
+    Usage:
+        @log_operation("create_issue", issue_type="bug")
+        def create_issue(...):
+            ...
+    """
+    from roadmap.common.logging.loggers import get_logger
+
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            logger = get_logger()
+            start_time = time.perf_counter()
+
+            logger.info(
+                "operation_started",
+                operation=operation,
+                **context,
+            )
+            try:
+                result = func(*args, **kwargs)
+                duration = time.perf_counter() - start_time
+                logger.info(
+                    "operation_completed",
+                    operation=operation,
+                    duration_ms=round(duration * 1000, 2),
+                    success=True,
+                    **context,
+                )
+                return result
+            except Exception as e:
+                duration = time.perf_counter() - start_time
+                logger.error(
+                    "operation_failed",
+                    operation=operation,
+                    duration_ms=round(duration * 1000, 2),
+                    success=False,
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                    **context,
+                )
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def should_sample(sample_rate: float = 0.1) -> bool:
+    """Determine if this log entry should be sampled.
+
+    Args:
+        sample_rate: Probability of sampling (0.0 to 1.0)
+                    0.1 = 10% sampling, 0.01 = 1% sampling
+
+    Returns:
+        True if this entry should be logged
+
+    Usage:
+        if should_sample(sample_rate=0.01):  # 1% sampling
+            logger.debug("Detailed operation info", ...)
+    """
+    return random.random() < sample_rate
+
+
+def configure_for_testing():
+    """Configure minimal logging for tests."""
+    structlog.configure(
+        processors=[
+            # Minimal processors for testing
+            structlog.stdlib.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            # Use PrintLogger for simple output
+            structlog.dev.ConsoleRenderer(),
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        logger_factory=structlog.PrintLoggerFactory(),
+        cache_logger_on_first_use=True,
+    )

roadmap/common/models/__init__.py

@@ -0,0 +1,44 @@
+"""Common data models."""
+
+from .cli_models import (  # noqa: F401
+    CleanupParams,
+    InitParams,
+    IssueCreateParams,
+    IssueGitParams,
+    IssueListParams,
+    IssueUpdateParams,
+)
+from .config_models import (  # noqa: F401
+    BehaviorConfig,
+    ExportConfig,
+    GitConfig,
+    GitHubConfig,
+    OutputConfig,
+    RoadmapConfig,
+)
+from .output_models import (  # noqa: F401
+    ColumnDef,
+    ColumnType,
+    TableData,
+)
+
+__all__ = [
+    # CLI models
+    "CleanupParams",
+    "InitParams",
+    "IssueCreateParams",
+    "IssueGitParams",
+    "IssueListParams",
+    "IssueUpdateParams",
+    # Config models
+    "BehaviorConfig",
+    "ExportConfig",
+    "GitConfig",
+    "GitHubConfig",
+    "OutputConfig",
+    "RoadmapConfig",
+    # Output models
+    "ColumnDef",
+    "ColumnType",
+    "TableData",
+]

roadmap/common/models/cli_models.py

@@ -0,0 +1,118 @@
+"""Dataclasses for clean CLI parameter passing.
+
+These models provide structured, documented parameter groups for complex CLI commands.
+Benefits:
+- Reduces cognitive load on function signatures
+- Self-documenting API with field descriptions
+- Easy to extend without breaking changes
+- Type-safe parameter handling
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class IssueCreateParams:
+    """Parameters for creating an issue."""
+
+    title: str
+    priority: str | None = None
+    issue_type: str | None = None
+    milestone: str | None = None
+    assignee: str | None = None
+    labels: tuple = field(default_factory=tuple)
+    estimate: float | None = None
+    depends_on: tuple = field(default_factory=tuple)
+    blocks: tuple = field(default_factory=tuple)
+    content: str | None = None
+
+
+@dataclass
+class IssueUpdateParams:
+    """Parameters for updating an issue."""
+
+    issue_id: str
+    title: str | None = None
+    priority: str | None = None
+    status: str | None = None
+    assignee: str | None = None
+    milestone: str | None = None
+    content: str | None = None
+    estimate: float | None = None
+    reason: str | None = None
+
+
+@dataclass
+class IssueGitParams:
+    """Git-related parameters for issues."""
+
+    git_branch: bool = False
+    checkout: bool = False
+    branch_name: str | None = None
+    force: bool = False
+
+
+@dataclass
+class IssueListParams:
+    """Parameters for listing issues."""
+
+    filter_type: str | None = None
+    milestone: str | None = None
+    backlog: bool = False
+    unassigned: bool = False
+    open: bool = False
+    blocked: bool = False
+    next_milestone: bool = False
+    assignee: str | None = None
+    my_issues: bool = False
+    status: str | None = None
+    priority: str | None = None
+    issue_type: str | None = None
+    overdue: bool = False
+
+
+@dataclass
+class InitParams:
+    """Parameters for initialization command."""
+
+    name: str
+    project_name: str | None = None
+    description: str | None = None
+    skip_project: bool = False
+    skip_github: bool = False
+    sync_backend: str = "github"
+    github_repo: str | None = None
+    github_token: str | None = None
+    interactive: bool = True
+    yes: bool = False
+    dry_run: bool = False
+    force: bool = False
+    template: str | None = None
+    template_path: str | None = None
+
+    def __post_init__(self):
+        """Validate parameters after initialization."""
+        from roadmap.common.constants import SyncBackend
+
+        # Validate sync_backend matches enum values
+        valid_backends = {backend.value for backend in SyncBackend}
+        if self.sync_backend not in valid_backends:
+            raise ValueError(
+                f"Invalid sync_backend '{self.sync_backend}'. "
+                f"Must be one of: {', '.join(sorted(valid_backends))}"
+            )
+
+
+@dataclass
+class CleanupParams:
+    """Parameters for cleanup command."""
+
+    keep: int = 10
+    days: int | None = None
+    dry_run: bool = False
+    force: bool = False
+    backups_only: bool = False
+    check_folders: bool = False
+    check_duplicates: bool = False
+    check_malformed: bool = False
+    verbose: bool = False

roadmap/common/models/config_models.py

@@ -0,0 +1,199 @@
+"""Configuration models and schemas for roadmap CLI.
+
+Provides Pydantic models for user-level and project-level configuration
+with validation and sensible defaults.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OutputConfig(BaseModel):
+    """Output formatting preferences."""
+
+    format: str = Field(
+        default="rich",
+        description="Default output format (rich, plain, json, csv, markdown, html)",
+    )
+    columns: list[str] = Field(
+        default_factory=list,
+        description="Default columns to display (empty = all)",
+    )
+    sort_by: str = Field(
+        default="",
+        description="Default sort specification (e.g., 'status:asc')",
+    )
+    model_config = ConfigDict(extra="allow")
+
+
+class ExportConfig(BaseModel):
+    """Export settings and behavior."""
+
+    directory: str = Field(
+        default=".roadmap/exports",
+        description="Directory for exported files (relative to project root)",
+    )
+    format: str = Field(
+        default="json",
+        description="Default export format (json, csv, markdown)",
+    )
+    include_metadata: bool = Field(
+        default=True,
+        description="Include metadata in exports",
+    )
+    auto_gitignore: bool = Field(
+        default=True,
+        description="Automatically add exports directory to .gitignore",
+    )
+    model_config = ConfigDict(extra="allow")
+
+
+class BehaviorConfig(BaseModel):
+    """Application behavior preferences."""
+
+    auto_branch_on_start: bool = Field(
+        default=False,
+        description="Automatically create git branch when starting work on issue",
+    )
+    confirm_destructive: bool = Field(
+        default=True,
+        description="Prompt before delete/archive operations",
+    )
+    show_tips: bool = Field(
+        default=True,
+        description="Show helpful tips in output",
+    )
+    include_closed_in_critical_path: bool = Field(
+        default=False,
+        description="Include closed issues in critical path analysis by default",
+    )
+    default_project_id: str | None = Field(
+        default=None,
+        description="Default project ID to use when creating milestones (auto-detected during init)",
+    )
+    model_config = ConfigDict(extra="allow")
+
+
+class GitConfig(BaseModel):
+    """Git integration settings."""
+
+    auto_commit: bool = Field(
+        default=False,
+        description="Automatically commit changes after operations",
+    )
+    commit_template: str = Field(
+        default="roadmap: {operation} {entity_id}",
+        description="Template for auto-generated commit messages",
+    )
+    model_config = ConfigDict(extra="allow")
+
+
+class GitHubConfig(BaseModel):
+    """GitHub integration settings."""
+
+    repository: str | None = Field(
+        default=None,
+        description="GitHub repository in format owner/repo",
+    )
+    owner: str | None = Field(
+        default=None,
+        description="GitHub repository owner",
+    )
+    repo: str | None = Field(
+        default=None,
+        description="GitHub repository name",
+    )
+    enabled: bool = Field(
+        default=False,
+        description="Whether GitHub integration is enabled",
+    )
+    sync_enabled: bool = Field(
+        default=False,
+        description="Whether GitHub sync is enabled",
+    )
+    sync_backend: str = Field(
+        default="github",
+        description="Sync backend to use (github or git)",
+    )
+    webhook_secret: str | None = Field(
+        default=None,
+        description="Webhook secret for GitHub events",
+    )
+    sync_settings: dict = Field(
+        default_factory=lambda: {
+            "bidirectional": True,
+            "auto_close": True,
+            "sync_labels": True,
+            "sync_milestones": True,
+            "auto_detect_from_git": True,  # Auto-detect owner/repo from git remote
+            "retry_attempts": 5,  # Number of retry attempts for API failures
+            "retry_delay": 1.0,  # Initial delay between retries (seconds)
+            "retry_backoff": 2.0,  # Exponential backoff multiplier
+            "batch_size": 50,  # Number of issues to process in parallel
+            "conflict_resolution": "prompt",  # Default: prompt, local, remote
+            "milestone_filter": {
+                "enabled": False,  # Enable milestone filtering
+                "states": ["open", "closed"],  # Filter by state
+                "names": [],  # Filter by milestone name patterns
+                "since": None,  # Filter by date (ISO format)
+                "until": None,  # Filter by date (ISO format)
+            },
+        },
+        description="Sync settings",
+    )
+    model_config = ConfigDict(extra="allow")
+
+
+class RoadmapConfig(BaseModel):
+    """Complete roadmap configuration schema."""
+
+    output: OutputConfig = Field(default_factory=OutputConfig)
+    export: ExportConfig = Field(default_factory=ExportConfig)
+    behavior: BehaviorConfig = Field(default_factory=BehaviorConfig)
+    git: GitConfig = Field(default_factory=GitConfig)
+    github: GitHubConfig = Field(default_factory=GitHubConfig)
+    model_config = ConfigDict(extra="allow")
+
+    def merge(self, other: "RoadmapConfig") -> "RoadmapConfig":
+        """Merge another config into this one (other takes precedence).
+
+        Args:
+            other: Config to merge (takes precedence)
+
+        Returns:
+            New RoadmapConfig with merged values
+        """
+        if other is None:
+            return self
+
+        return RoadmapConfig(
+            output=OutputConfig(
+                **{
+                    **self.output.model_dump(),
+                    **other.output.model_dump(exclude_unset=True),
+                }
+            ),
+            export=ExportConfig(
+                **{
+                    **self.export.model_dump(),
+                    **other.export.model_dump(exclude_unset=True),
+                }
+            ),
+            behavior=BehaviorConfig(
+                **{
+                    **self.behavior.model_dump(),
+                    **other.behavior.model_dump(exclude_unset=True),
+                }
+            ),
+            git=GitConfig(
+                **{
+                    **self.git.model_dump(),
+                    **other.git.model_dump(exclude_unset=True),
+                }
+            ),
+            github=GitHubConfig(
+                **{
+                    **self.github.model_dump(),
+                    **other.github.model_dump(exclude_unset=True),
+                }
+            ),
+        )