ado-workflows 0.1.0__py3-none-any.whl

ado_workflows/__init__.py

@@ -0,0 +1,99 @@
+"""ado-workflows: Azure DevOps workflow automation library.
+
+Three-layer API for Azure DevOps operations:
+- Layer 1 — Primitives: pure functions (URL parsing, git inspection, date parsing)
+- Layer 2 — Context: stateful caching (RepositoryContext, thread-safe)
+- Layer 3 — PR Context: composed workflows (AzureDevOpsPRContext)
+"""
+
+from __future__ import annotations
+
+from ado_workflows.auth import AZURE_DEVOPS_RESOURCE_ID, ConnectionFactory
+from ado_workflows.client import AdoClient
+from ado_workflows.comments import (
+    analyze_pr_comments,
+    post_comment,
+    reply_to_comment,
+    resolve_comments,
+    sanitize_ado_response,
+)
+from ado_workflows.context import (
+    RepositoryContext,
+    clear_repository_context,
+    get_context_status,
+    get_repository_context,
+    set_repository_context,
+)
+from ado_workflows.discovery import (
+    discover_repositories,
+    infer_target_repository,
+    inspect_git_repository,
+)
+from ado_workflows.lifecycle import create_pull_request
+from ado_workflows.models import (
+    VOTE_TEXT,
+    ApprovalStatus,
+    AuthorSample,
+    CommentAnalysis,
+    CommentInfo,
+    CommentSummary,
+    CreatedPR,
+    PendingPR,
+    PendingReviewResult,
+    ResolveResult,
+    ReviewerInfo,
+    ReviewStatus,
+    VoteStatus,
+)
+from ado_workflows.parsing import parse_ado_date, parse_ado_url
+from ado_workflows.pr import AzureDevOpsPRContext, establish_pr_context
+from ado_workflows.review import (
+    analyze_pending_reviews,
+    fetch_required_approvals,
+    fetch_vote_timestamps,
+    get_review_status,
+)
+from ado_workflows.votes import deduplicate_team_containers, determine_vote_status
+
+__all__: list[str] = [
+    "AZURE_DEVOPS_RESOURCE_ID",
+    "VOTE_TEXT",
+    "AdoClient",
+    "ApprovalStatus",
+    "AuthorSample",
+    "AzureDevOpsPRContext",
+    "CommentAnalysis",
+    "CommentInfo",
+    "CommentSummary",
+    "ConnectionFactory",
+    "CreatedPR",
+    "PendingPR",
+    "PendingReviewResult",
+    "RepositoryContext",
+    "ResolveResult",
+    "ReviewStatus",
+    "ReviewerInfo",
+    "VoteStatus",
+    "analyze_pending_reviews",
+    "analyze_pr_comments",
+    "clear_repository_context",
+    "create_pull_request",
+    "deduplicate_team_containers",
+    "determine_vote_status",
+    "discover_repositories",
+    "establish_pr_context",
+    "fetch_required_approvals",
+    "fetch_vote_timestamps",
+    "get_context_status",
+    "get_repository_context",
+    "get_review_status",
+    "infer_target_repository",
+    "inspect_git_repository",
+    "parse_ado_date",
+    "parse_ado_url",
+    "post_comment",
+    "reply_to_comment",
+    "resolve_comments",
+    "sanitize_ado_response",
+    "set_repository_context",
+]

ado_workflows/auth.py

@@ -0,0 +1,83 @@
+"""Azure DevOps authentication — DefaultAzureCredential → Connection bridge.
+
+Bridges azure-identity's ``DefaultAzureCredential`` into the azure-devops SDK's
+msrest-based auth layer.  ``ConnectionFactory`` handles per-org connection caching
+and proactive token refresh before expiry.
+
+Typical usage::
+
+    factory = ConnectionFactory()  # uses DefaultAzureCredential
+    connection = factory.get_connection("https://dev.azure.com/MyOrg")
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+from azure.devops.connection import Connection
+from azure.identity import DefaultAzureCredential
+from msrest.authentication import BasicTokenAuthentication
+
+if TYPE_CHECKING:
+    from azure.core.credentials import TokenCredential
+
+AZURE_DEVOPS_RESOURCE_ID: str = "499b84ac-1321-427f-aa17-267ca6975798"
+"""Well-known Azure DevOps resource identifier for token acquisition."""
+
+_SCOPE: str = f"{AZURE_DEVOPS_RESOURCE_ID}/.default"
+_TOKEN_REFRESH_BUFFER_SECONDS: int = 300  # refresh 5 min before expiry
+
+
+class ConnectionFactory:
+    """Creates and caches Azure DevOps SDK connections per organization URL.
+
+    Bridges ``azure-identity``'s :class:`DefaultAzureCredential` into the
+    azure-devops SDK's msrest-based auth layer, handling token refresh and
+    per-org connection caching.
+
+    Parameters
+    ----------
+    credential:
+        Optional :class:`TokenCredential` for dependency injection / testing.
+        Defaults to :class:`DefaultAzureCredential` when *None*.
+    """
+
+    def __init__(self, credential: TokenCredential | None = None) -> None:
+        self._credential: Any = credential or DefaultAzureCredential()
+        self._connections: dict[str, Connection] = {}
+        self._token_expiry: dict[str, float] = {}
+
+    def get_connection(self, org_url: str) -> Connection:
+        """Get or create a cached connection for *org_url*.
+
+        Returns a cached :class:`Connection` if the token is still valid
+        (more than 5 minutes until expiry).  Otherwise acquires a fresh
+        token and creates a new connection.
+        """
+        key = _normalize_org_url(org_url)
+        now = time.time()
+
+        if key in self._connections:
+            expiry = self._token_expiry.get(key, 0.0)
+            if now < expiry - _TOKEN_REFRESH_BUFFER_SECONDS:
+                return self._connections[key]
+
+        token = self._credential.get_token(_SCOPE)
+        creds = BasicTokenAuthentication({"access_token": token.token})
+        connection = Connection(base_url=key, creds=creds)
+
+        self._connections[key] = connection
+        self._token_expiry[key] = token.expires_on
+
+        return connection
+
+    def clear_cache(self) -> None:
+        """Remove all cached connections and token expiry records."""
+        self._connections.clear()
+        self._token_expiry.clear()
+
+
+def _normalize_org_url(org_url: str) -> str:
+    """Normalize *org_url* to a consistent form for cache-key usage."""
+    return org_url.rstrip("/")

ado_workflows/client.py

@@ -0,0 +1,76 @@
+"""Typed accessors for Azure DevOps SDK clients.
+
+Wraps :meth:`Connection.get_client` with lazy, cached properties that
+provide type-safe access to the Git, Core, and Work Item Tracking clients.
+
+Typical usage::
+
+    from ado_workflows.auth import ConnectionFactory
+    from ado_workflows.client import AdoClient
+
+    factory = ConnectionFactory()
+    connection = factory.get_connection("https://dev.azure.com/MyOrg")
+    client = AdoClient(connection)
+
+    repos = client.git.get_repositories("MyProject")
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from azure.devops.connection import Connection
+    from azure.devops.v7_1.core.core_client import CoreClient
+    from azure.devops.v7_1.git.git_client import GitClient
+    from azure.devops.v7_1.policy.policy_client import PolicyClient
+    from azure.devops.v7_1.work_item_tracking.work_item_tracking_client import (
+        WorkItemTrackingClient,
+    )
+
+_GIT_CLIENT_PATH = "azure.devops.v7_1.git.git_client.GitClient"
+_CORE_CLIENT_PATH = "azure.devops.v7_1.core.core_client.CoreClient"
+_POLICY_CLIENT_PATH = "azure.devops.v7_1.policy.policy_client.PolicyClient"
+_WIT_CLIENT_PATH = (
+    "azure.devops.v7_1.work_item_tracking"
+    ".work_item_tracking_client.WorkItemTrackingClient"
+)
+
+
+class AdoClient:
+    """Typed, lazy accessor for Azure DevOps SDK clients.
+
+    Each client property is initialized on first access and cached for
+    the lifetime of this instance.  If the underlying connection's token
+    expires, create a new ``AdoClient`` from a fresh connection.
+
+    Parameters
+    ----------
+    connection:
+        An authenticated :class:`Connection` (typically from
+        :meth:`ConnectionFactory.get_connection`).
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self._connection: Any = connection
+
+    @cached_property
+    def git(self) -> GitClient:
+        """Git operations: repositories, pull requests, threads, commits."""
+        return self._connection.get_client(_GIT_CLIENT_PATH)
+
+    @cached_property
+    def core(self) -> CoreClient:
+        """Core operations: projects, teams."""
+        return self._connection.get_client(_CORE_CLIENT_PATH)
+
+    @cached_property
+    def policy(self) -> PolicyClient:
+        """Policy operations: evaluations, configurations, types."""
+        return self._connection.get_client(_POLICY_CLIENT_PATH)
+
+    @cached_property
+    def work_items(self) -> WorkItemTrackingClient:
+        """Work item operations: queries, work items."""
+        return self._connection.get_client(_WIT_CLIENT_PATH)

ado_workflows/comments.py

@@ -0,0 +1,346 @@
+"""Comment analysis, response sanitization, and write operations for Azure DevOps PRs.
+
+Provides :func:`sanitize_ado_response` (pure utility for Windows-1252
+smart-quote fix), :func:`analyze_pr_comments` (SDK-based thread
+analysis returning a typed :class:`~models.CommentAnalysis`),
+:func:`post_comment`, :func:`reply_to_comment`, and
+:func:`resolve_comments` (SDK-based write operations).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from actionable_errors import ActionableError
+
+from ado_workflows.models import (
+    AuthorSample,
+    CommentAnalysis,
+    CommentInfo,
+    CommentSummary,
+    ResolveResult,
+)
+
+if TYPE_CHECKING:
+    from ado_workflows.client import AdoClient
+
+from azure.devops.v7_1.git.models import (
+    Comment,
+    GitPullRequestCommentThread,
+)
+
+
+def sanitize_ado_response(raw_data: bytes | str) -> str:
+    """Fix Windows-1252 smart-quote corruption in ADO responses.
+
+    Azure DevOps REST API sometimes returns Windows-1252 smart quotes
+    (0x91-0x94) which are invalid UTF-8.  This function replaces those
+    bytes with their UTF-8 equivalents before decoding.
+
+    String inputs pass through unchanged.
+
+    Args:
+        raw_data: Raw bytes or string from an ADO API response.
+
+    Returns:
+        A properly decoded UTF-8 string.
+    """
+    if isinstance(raw_data, str):
+        return raw_data
+
+    raw_bytes: bytes = bytes(raw_data) if not isinstance(raw_data, bytes) else raw_data
+
+    # Windows-1252 → UTF-8 smart quote replacements
+    # 0x91 = left single quote  (') → U+2018
+    # 0x92 = right single quote (') → U+2019
+    # 0x93 = left double quote  (") → U+201C
+    # 0x94 = right double quote (") → U+201D
+    sanitized = raw_bytes.replace(b"\x91", b"\xe2\x80\x98")
+    sanitized = sanitized.replace(b"\x92", b"\xe2\x80\x99")
+    sanitized = sanitized.replace(b"\x93", b"\xe2\x80\x9c")
+    sanitized = sanitized.replace(b"\x94", b"\xe2\x80\x9d")
+
+    return sanitized.decode("utf-8")
+
+
+def analyze_pr_comments(
+    client: AdoClient,
+    pr_id: int,
+    project: str,
+    repository: str,
+) -> CommentAnalysis:
+    """Analyze all comment threads on a pull request.
+
+    Fetches threads via ``client.git.get_threads()``, categorizes by
+    status, extracts author statistics, and identifies active (unresolved)
+    comments.  Applies :func:`sanitize_ado_response` to comment content
+    strings.
+
+    Args:
+        client: An authenticated :class:`~client.AdoClient`.
+        pr_id: Pull request ID.
+        project: Azure DevOps project name or GUID.
+        repository: Repository name or GUID.
+
+    Returns:
+        A :class:`~models.CommentAnalysis` with thread statistics,
+        author breakdowns, and active comments.
+    """
+    threads: list[Any] = client.git.get_threads(repository, pr_id, project=project)
+
+    # Categorize threads by status
+    active_threads = [t for t in threads if t.status == "active"]
+    fixed_threads = [t for t in threads if t.status == "fixed"]
+    total_threads = len(threads)
+
+    active_percentage = (
+        round(len(active_threads) / total_threads * 100, 1)
+        if total_threads > 0
+        else 0.0
+    )
+
+    # Analyze comments: authors, content, file context
+    comment_authors: dict[str, int] = {}
+    all_comments: list[CommentInfo] = []
+    active_comments: list[CommentInfo] = []
+
+    for thread in threads:
+        # Extract file context from thread_context
+        file_path: str | None = None
+        line_start: int | None = None
+        line_end: int | None = None
+
+        thread_context = thread.thread_context
+        if thread_context is not None:
+            file_path = thread_context.file_path
+
+            # Prefer right (new) side, fall back to left (old) side
+            if thread_context.right_file_start is not None:
+                line_start = thread_context.right_file_start.line
+            if line_start is None and thread_context.left_file_start is not None:
+                line_start = thread_context.left_file_start.line
+
+            if thread_context.right_file_end is not None:
+                line_end = thread_context.right_file_end.line
+            if line_end is None and thread_context.left_file_end is not None:
+                line_end = thread_context.left_file_end.line
+
+        for comment in thread.comments or []:
+            author_name: str = comment.author.display_name
+            comment_authors[author_name] = comment_authors.get(author_name, 0) + 1
+
+            content: str = sanitize_ado_response(comment.content or "")
+            preview = (
+                content[:200] + "..." if len(content) > 200 else content
+            )
+
+            info = CommentInfo(
+                thread_id=thread.id,
+                thread_status=thread.status or "unknown",
+                author=author_name,
+                content_preview=preview,
+                full_content=content,
+                created_date=comment.published_date,
+                is_deleted=comment.is_deleted or False,
+                file_path=file_path,
+                line_start=line_start,
+                line_end=line_end,
+            )
+            all_comments.append(info)
+            if thread.status == "active":
+                active_comments.append(info)
+
+    # Build author samples (latest non-deleted comment per author)
+    author_samples: dict[str, AuthorSample] = {}
+    for author_name in comment_authors:
+        author_comments = [
+            c for c in all_comments
+            if c.author == author_name and not c.is_deleted
+        ]
+        if author_comments:
+            latest = author_comments[-1]
+            author_samples[author_name] = AuthorSample(
+                count=comment_authors[author_name],
+                latest_comment=latest.content_preview,
+                latest_status=latest.thread_status,
+            )
+
+    return CommentAnalysis(
+        pr_id=pr_id,
+        comment_summary=CommentSummary(
+            total_threads=total_threads,
+            active_threads=len(active_threads),
+            fixed_threads=len(fixed_threads),
+            active_percentage=active_percentage,
+        ),
+        comment_authors=comment_authors,
+        author_samples=author_samples,
+        active_comments=active_comments,
+        resolution_ready=len(active_threads) == 0,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Phase 6d — Comment write operations
+# ---------------------------------------------------------------------------
+
+
+def post_comment(
+    client: AdoClient,
+    repository: str,
+    pr_id: int,
+    content: str,
+    project: str,
+    *,
+    status: str = "active",
+) -> int:
+    """Create a new comment thread on a pull request.
+
+    Args:
+        client: An authenticated :class:`~client.AdoClient`.
+        repository: Repository name or GUID.
+        pr_id: Pull request ID.
+        content: Comment body text (must not be empty).
+        project: Azure DevOps project name or GUID.
+        status: Thread status (default ``"active"``).
+
+    Returns:
+        The new thread ID.
+
+    Raises:
+        ActionableError: When *content* is empty/whitespace or the SDK fails.
+    """
+    if not content or not content.strip():
+        raise ActionableError.validation(
+            service="AzureDevOps",
+            field_name="content",
+            reason="Cannot post a comment with empty content.",
+        )
+
+    thread = GitPullRequestCommentThread(
+        comments=[Comment(content=content)],
+        status=status,
+    )
+
+    try:
+        response = client.git.create_thread(thread, repository, pr_id, project=project)
+    except Exception as exc:
+        raise ActionableError.connection(
+            service="AzureDevOps",
+            url=f"{repository}/pullrequests/{pr_id}/threads",
+            raw_error=str(exc),
+        ) from exc
+
+    return int(response.id)
+
+
+def reply_to_comment(
+    client: AdoClient,
+    repository: str,
+    pr_id: int,
+    thread_id: int,
+    content: str,
+    project: str,
+) -> int:
+    """Add a reply to an existing comment thread.
+
+    Args:
+        client: An authenticated :class:`~client.AdoClient`.
+        repository: Repository name or GUID.
+        pr_id: Pull request ID.
+        thread_id: Existing thread ID to reply to.
+        content: Reply body text (must not be empty).
+        project: Azure DevOps project name or GUID.
+
+    Returns:
+        The new comment ID.
+
+    Raises:
+        ActionableError: When *content* is empty/whitespace or the SDK fails.
+    """
+    if not content or not content.strip():
+        raise ActionableError.validation(
+            service="AzureDevOps",
+            field_name="content",
+            reason="Cannot reply with empty content.",
+        )
+
+    comment = Comment(content=content, parent_comment_id=1)
+
+    try:
+        response = client.git.create_comment(
+            comment, repository, pr_id, thread_id, project=project,
+        )
+    except Exception as exc:
+        raise ActionableError.connection(
+            service="AzureDevOps",
+            url=f"{repository}/pullrequests/{pr_id}/threads/{thread_id}/comments",
+            raw_error=str(exc),
+        ) from exc
+
+    return int(response.id)
+
+
+def resolve_comments(
+    client: AdoClient,
+    repository: str,
+    pr_id: int,
+    thread_ids: list[int],
+    project: str,
+    *,
+    status: str = "fixed",
+) -> ResolveResult:
+    """Batch-resolve comment threads with partial-success reporting.
+
+    Iterates *thread_ids* and calls ``client.git.update_thread()`` for
+    each.  Threads already in the target status are skipped.  Individual
+    failures are collected — the function never raises on a single thread
+    failure.
+
+    Args:
+        client: An authenticated :class:`~client.AdoClient`.
+        repository: Repository name or GUID.
+        pr_id: Pull request ID.
+        thread_ids: Thread IDs to resolve.
+        project: Azure DevOps project name or GUID.
+        status: Target thread status (default ``"fixed"``).
+
+    Returns:
+        A :class:`~models.ResolveResult` partitioning threads into
+        *resolved*, *errors*, and *skipped*.
+    """
+    resolved: list[int] = []
+    errors: list[ActionableError] = []
+    skipped: list[int] = []
+
+    if not thread_ids:
+        return ResolveResult(resolved=resolved, errors=errors, skipped=skipped)
+
+    # Fetch current thread statuses for skip detection
+    all_threads: list[Any] = client.git.get_threads(
+        repository, pr_id, project=project,
+    )
+    current_status: dict[int, str] = {t.id: t.status for t in all_threads}
+
+    for tid in thread_ids:
+        # Skip threads already in the target status
+        if current_status.get(tid) == status:
+            skipped.append(tid)
+            continue
+
+        thread_update = GitPullRequestCommentThread(status=status)
+        try:
+            client.git.update_thread(
+                thread_update, repository, pr_id, tid, project=project,
+            )
+            resolved.append(tid)
+        except Exception as exc:
+            err = ActionableError.internal(
+                service="AzureDevOps",
+                operation=f"resolve_thread({tid})",
+                raw_error=str(exc),
+            )
+            err.context = {"thread_id": tid}
+            errors.append(err)
+
+    return ResolveResult(resolved=resolved, errors=errors, skipped=skipped)