ado-workflows 0.2.2__tar.gz → 0.3.0__tar.gz

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 <!-- version list -->
 
+## v0.3.0 (2026-03-27)
+
+### Chores
+
+- **lint**: Add pydocstyle rules and fix docstring issues
+  ([`4438527`](https://github.com/grimlor/ado-workflows/commit/4438527cc66f000e84b6ef183514f2c12efafe79))
+
+### Code Style
+
+- `task format` changes only
+  ([`36082cd`](https://github.com/grimlor/ado-workflows/commit/36082cd2f94b3d179d7db20a9be0cce9d913c822))
+
+### Features
+
+- **content**: Add exclude_extensions filtering and completed-PR fallback
+  ([`87926d0`](https://github.com/grimlor/ado-workflows/commit/87926d09cd3a30ac5fbcb6050086c970b7eb5591))
+
+
 ## v0.2.2 (2026-03-19)
 
 ### Bug Fixes

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ado-workflows
-Version: 0.2.2
+Version: 0.3.0
 Summary: Azure DevOps workflow automation library — PR context, repository discovery, and SDK client wrappers
 Project-URL: Repository, https://github.com/grimlor/ado-workflows
 Author: Jack Pines

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ado-workflows"
-version = "0.2.2"
+version = "0.3.0"
 description = "Azure DevOps workflow automation library — PR context, repository discovery, and SDK client wrappers"
 readme = "README.md"
 requires-python = ">=3.12,<3.14"
@@ -77,11 +77,14 @@ select = [
     "SIM",      # flake8-simplify
     "TCH",      # flake8-type-checking
     "RUF",      # ruff-specific rules
+    "D",        # pydocstyle
     "PLC0415",  # import-outside-top-level
     "PLC2701",  # import-private-name (preview)
 ]
 ignore = [
-    "E501",  # line length (handled by formatter)
+    "E501",   # line length (handled by formatter)
+    "D212",   # multi-line-summary-first-line (conflicts with D213)
+    "D203",   # one-blank-line-before-class (conflicts with D211)
 ]
 
 [tool.ruff.lint.isort]
@@ -92,6 +95,10 @@ combine-as-imports = true
 "tests/**/*.py" = [
     "PLC0415",  # import-outside-top-level — tests may import inside functions
     "PLC2701",  # import-private-name — testing internal state is intentional
+    "D205",     # BDD Given/When/Then blocks aren't summary+body
+    "D400",     # BDD steps don't end with periods
+    "D415",     # same as D400
+    "D401",     # fixture docstrings are descriptive, not imperative
 ]
 
 [tool.ruff.format]

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/__init__.py

@@ -1,4 +1,5 @@
-"""ado-workflows: Azure DevOps workflow automation library.
+"""
+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)

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/auth.py

@@ -1,4 +1,5 @@
-"""Azure DevOps authentication — DefaultAzureCredential → Connection bridge.
+"""
+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
@@ -35,7 +36,8 @@ _TOKEN_REFRESH_BUFFER_SECONDS: int = 300  # refresh 5 min before expiry
 
 
 class ConnectionFactory:
-    """Creates and caches Azure DevOps SDK connections per organization URL.
+    """
+    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
@@ -46,15 +48,18 @@ class ConnectionFactory:
     credential:
         Optional :class:`TokenCredential` for dependency injection / testing.
         Defaults to :class:`DefaultAzureCredential` when *None*.
+
     """
 
     def __init__(self, credential: TokenCredential | None = None) -> None:
+        """Initialize with an optional credential; defaults to DefaultAzureCredential."""
         self._credential: TokenCredential = 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*.
+        """
+        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
@@ -94,7 +99,8 @@ def _normalize_org_url(org_url: str) -> str:
 
 
 def get_current_user(client: AdoClient) -> UserIdentity:
-    """Return the identity of the authenticated user.
+    """
+    Return the identity of the authenticated user.
 
     Uses :class:`LocationClient`'s ``get_connection_data()`` to resolve
     the authenticated user from the active connection.
@@ -108,6 +114,7 @@ def get_current_user(client: AdoClient) -> UserIdentity:
 
     Raises:
         ActionableError: When credentials are invalid or the call fails.
+
     """
     try:
         conn_data = client.location.get_connection_data()

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/client.py

@@ -1,4 +1,5 @@
-"""Typed accessors for Azure DevOps SDK clients.
+"""
+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.
@@ -40,7 +41,8 @@ _WIT_CLIENT_PATH = (
 
 
 class AdoClient:
-    """Typed, lazy accessor for Azure DevOps SDK clients.
+    """
+    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
@@ -51,9 +53,11 @@ class AdoClient:
     connection:
         An authenticated :class:`Connection` (typically from
         :meth:`ConnectionFactory.get_connection`).
+
     """
 
     def __init__(self, connection: Connection) -> None:
+        """Initialize the client wrapper with an authenticated connection."""
         self._connection: Connection = connection
 
     @cached_property

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/comments.py

@@ -1,4 +1,5 @@
-"""Comment analysis, response sanitization, and write operations for Azure DevOps PRs.
+"""
+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
@@ -40,7 +41,8 @@ from azure.devops.v7_1.git.models import (
 
 
 def sanitize_ado_response(raw_data: bytes | str) -> str:
-    """Fix Windows-1252 smart-quote corruption in ADO responses.
+    """
+    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
@@ -53,6 +55,7 @@ def sanitize_ado_response(raw_data: bytes | str) -> str:
 
     Returns:
         A properly decoded UTF-8 string.
+
     """
     if isinstance(raw_data, str):
         return raw_data
@@ -78,7 +81,8 @@ def analyze_pr_comments(
     project: str,
     repository: str,
 ) -> CommentAnalysis:
-    """Analyze all comment threads on a pull request.
+    """
+    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)
@@ -94,6 +98,7 @@ def analyze_pr_comments(
     Returns:
         A :class:`~models.CommentAnalysis` with thread statistics,
         author breakdowns, and active comments.
+
     """
     threads = client.git.get_threads(repository, pr_id, project=project)
 
@@ -199,7 +204,8 @@ def post_comment(
     line_number: int | None = None,
     iteration_context: IterationContext | None = None,
 ) -> int:
-    """Create a new comment thread on a pull request.
+    """
+    Create a new comment thread on a pull request.
 
     When *file_path* and *line_number* are provided, the comment is anchored
     to that line in the PR diff.  If *iteration_context* is also provided,
@@ -224,6 +230,7 @@ def post_comment(
     Raises:
         ActionableError: When *content* is empty/whitespace, when
             *file_path*/*line_number* are inconsistent, or when the SDK fails.
+
     """
     if not content or not content.strip():
         raise ActionableError.validation(
@@ -300,7 +307,8 @@ def post_comments(
     *,
     dry_run: bool = False,
 ) -> PostingResult:
-    """Batch-post comment threads with per-comment file/line positioning.
+    """
+    Batch-post comment threads with per-comment file/line positioning.
 
     Each :class:`~models.CommentPayload` carries its own content, file_path,
     and line_number.  Iteration context is resolved once and shared across
@@ -322,6 +330,7 @@ def post_comments(
 
     Returns:
         :class:`~models.PostingResult` with successes, failures, and skipped.
+
     """
     if not comments:
         return PostingResult(posted=[], failures=[], skipped=[], dry_run=dry_run)
@@ -364,8 +373,7 @@ def post_comments(
                 operation="post_comment",
                 raw_error=str(exc),
                 suggestion=(
-                    f"Comment {i} failed to post. "
-                    "Check content, file path, and line number."
+                    f"Comment {i} failed to post. Check content, file path, and line number."
                 ),
             )
             err.context = {
@@ -390,7 +398,8 @@ def reply_to_comment(
     content: str,
     project: str,
 ) -> int:
-    """Add a reply to an existing comment thread.
+    """
+    Add a reply to an existing comment thread.
 
     Args:
         client: An authenticated :class:`~client.AdoClient`.
@@ -405,6 +414,7 @@ def reply_to_comment(
 
     Raises:
         ActionableError: When *content* is empty/whitespace or the SDK fails.
+
     """
     if not content or not content.strip():
         raise ActionableError.validation(
@@ -442,7 +452,8 @@ def resolve_comments(
     *,
     status: str = "fixed",
 ) -> ResolveResult:
-    """Batch-resolve comment threads with partial-success reporting.
+    """
+    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
@@ -460,6 +471,7 @@ def resolve_comments(
     Returns:
         A :class:`~models.ResolveResult` partitioning threads into
         *resolved*, *errors*, and *skipped*.
+
     """
     resolved: list[int] = []
     errors: list[ActionableError] = []

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/content.py

@@ -1,4 +1,5 @@
-"""File content retrieval from Azure DevOps repositories.
+"""
+File content retrieval from Azure DevOps repositories.
 
 Provides single-file retrieval (:func:`get_file_content`) and batch
 PR-scoped retrieval (:func:`get_changed_file_contents`) with
@@ -28,7 +29,8 @@ def get_file_content(
     version: str | None = None,
     version_type: str = "branch",
 ) -> FileContent:
-    """Fetch a single file's content from a repository ref.
+    """
+    Fetch a single file's content from a repository ref.
 
     Args:
         client: An authenticated :class:`~client.AdoClient`.
@@ -43,6 +45,7 @@ def get_file_content(
 
     Raises:
         ActionableError: When the file does not exist or cannot be fetched.
+
     """
     try:
         version_descriptor = None
@@ -101,12 +104,17 @@ def get_changed_file_contents(
     project: str,
     *,
     file_paths: list[str] | None = None,
+    exclude_extensions: list[str] | None = None,
 ) -> ContentResult:
-    """Fetch file contents for files changed in a PR.
+    """
+    Fetch file contents for files changed in a PR.
 
     Uses the PR's source branch ref. If *file_paths* is ``None``, discovers
     changed files from the latest iteration and fetches all of them.
 
+    For completed PRs whose source branch has been deleted, falls back to
+    the ``last_merge_source_commit`` SHA.
+
     Uses partial-success semantics: files that fail to fetch are collected
     in :attr:`ContentResult.failures` with the path and error, not raised.
 
@@ -117,11 +125,15 @@ def get_changed_file_contents(
         project: Azure DevOps project name or GUID.
         file_paths: Optional list of specific file paths to fetch.
             If ``None``, fetches all changed files.
+        exclude_extensions: Optional list of file extensions to skip
+            (e.g. ``[".lock", ".json"]``).  Matched case-insensitively.
+            A leading dot is added if missing.
 
     Returns:
         :class:`~models.ContentResult` with files and failures.
+
     """
-    # Get the source branch for fetching content
+    # Get the PR metadata for branch/commit resolution
     try:
         pr = client.git.get_pull_request_by_id(pr_id, project=project)
         branch = pr.source_ref_name.replace("refs/heads/", "")
@@ -141,18 +153,72 @@ def get_changed_file_contents(
         except Exception:
             file_paths = []
 
+    # Apply extension filtering before fetching
+    if exclude_extensions:
+        normalized = [
+            ext.lower() if ext.startswith(".") else f".{ext.lower()}" for ext in exclude_extensions
+        ]
+        file_paths = [
+            p for p in file_paths if not any(p.lower().endswith(ext) for ext in normalized)
+        ]
+
     if not file_paths:
         return ContentResult(files=[], failures=[])
 
+    # Determine version reference: branch first, commit SHA fallback for completed PRs
+    version = branch
+    version_type = "branch"
+
     # Fetch each file with partial-success
     files: list[FileContent] = []
     failures: list[ActionableError] = []
 
     for path in file_paths:
         try:
-            fc = get_file_content(client, repository, path, project, version=branch)
+            fc = get_file_content(
+                client, repository, path, project, version=version, version_type=version_type
+            )
             files.append(fc)
         except Exception as exc:
+            # For completed PRs, try fallback to merge commit SHA
+            merge_commit = pr.last_merge_source_commit
+            if (
+                pr.status == "completed"
+                and version_type == "branch"
+                and merge_commit is not None
+                and merge_commit.commit_id is not None
+            ):
+                try:
+                    fc = get_file_content(
+                        client,
+                        repository,
+                        path,
+                        project,
+                        version=merge_commit.commit_id,
+                        version_type="commit",
+                    )
+                    files.append(fc)
+                    continue
+                except Exception:
+                    pass  # Fall through to original error handling
+
+            # For completed PRs with deleted branch and no merge commit, raise
+            if (
+                pr.status == "completed"
+                and ("TF401174" in str(exc) or "does not exist" in str(exc).lower())
+                and (merge_commit is None or merge_commit.commit_id is None)
+            ):
+                raise ActionableError.not_found(
+                    service="AzureDevOps",
+                    resource_type="PR source",
+                    resource_id=f"PR {pr_id}",
+                    raw_error=str(exc),
+                    suggestion=(
+                        f"Source branch for PR {pr_id} has been deleted and no "
+                        f"merge commit is available. The PR source code cannot be retrieved."
+                    ),
+                ) from exc
+
             err = ActionableError.internal(
                 service="ado-workflows",
                 operation="get_file_content",

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/context.py

@@ -1,4 +1,5 @@
-"""Layer 2 — Repository context management with caching and thread-safety.
+"""
+Layer 2 — Repository context management with caching and thread-safety.
 
 Provides session-level repository context so that multiple tool calls within
 a single MCP session share the same discovered repository information without
@@ -29,7 +30,8 @@ _SERVICE = "Azure DevOps"
 
 
 class RepositoryContext:
-    """Thread-safe, session-level repository context manager.
+    """
+    Thread-safe, session-level repository context manager.
 
     All public methods are classmethods operating on class-level state
     (effectively a singleton).  Every method acquires ``_lock`` before
@@ -53,7 +55,8 @@ class RepositoryContext:
 
     @classmethod
     def set(cls, working_directory: str) -> dict[str, Any]:
-        """Set the active repository context for subsequent tool operations.
+        """
+        Set the active repository context for subsequent tool operations.
 
         Validates the path, runs discovery, and caches the result.  On
         failure the previous context is cleared so callers never operate
@@ -117,7 +120,8 @@ class RepositoryContext:
 
     @classmethod
     def get(cls, working_directory: str | None = None) -> dict[str, Any]:
-        """Get repository info — cached, overridden, or via intelligent discovery.
+        """
+        Get repository info — cached, overridden, or via intelligent discovery.
 
         * No args + cache → return cached (source ``"cached"``)
         * No args + no cache → attempt intelligent discovery (source ``"intelligent_discovery"``)
@@ -199,7 +203,8 @@ class RepositoryContext:
 
     @classmethod
     def _discover(cls, working_directory: str | None) -> dict[str, Any]:
-        """Run git discovery via Layer 1 primitives.
+        """
+        Run git discovery via Layer 1 primitives.
 
         Uses :func:`discover_repositories` + :func:`infer_target_repository`
         to find and select a repository.  If *working_directory* is ``None``,
@@ -237,20 +242,20 @@ class RepositoryContext:
 
 
 def set_repository_context(working_directory: str) -> dict[str, Any]:
-    """Convenience wrapper for :meth:`RepositoryContext.set`."""
+    """Delegate to :meth:`RepositoryContext.set`."""
     return RepositoryContext.set(working_directory)
 
 
 def get_repository_context(working_directory: str | None = None) -> dict[str, Any]:
-    """Convenience wrapper for :meth:`RepositoryContext.get`."""
+    """Delegate to :meth:`RepositoryContext.get`."""
     return RepositoryContext.get(working_directory)
 
 
 def get_context_status() -> dict[str, Any]:
-    """Convenience wrapper for :meth:`RepositoryContext.status`."""
+    """Delegate to :meth:`RepositoryContext.status`."""
     return RepositoryContext.status()
 
 
 def clear_repository_context() -> dict[str, Any]:
-    """Convenience wrapper for :meth:`RepositoryContext.clear`."""
+    """Delegate to :meth:`RepositoryContext.clear`."""
     return RepositoryContext.clear()

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/discovery.py

@@ -1,4 +1,5 @@
-"""Layer 1 — Git repository discovery primitives for Azure DevOps.
+"""
+Layer 1 — Git repository discovery primitives for Azure DevOps.
 
 Pure functions (except for subprocess calls to ``git``), no state, no SDK
 dependency.  Designed for single- and multi-repo workspaces.
@@ -14,7 +15,8 @@ from ado_workflows.parsing import parse_ado_url
 
 
 def inspect_git_repository(repo_path: str) -> dict[str, Any] | None:
-    """Extract Azure DevOps metadata from a local git repository.
+    """
+    Extract Azure DevOps metadata from a local git repository.
 
     Runs ``git config --get remote.origin.url`` and parses the result.
 
@@ -25,6 +27,7 @@ def inspect_git_repository(repo_path: str) -> dict[str, Any] | None:
         A dict with keys ``path``, ``name``, ``organization``, ``project``,
         ``remote_url``, ``org_url``, and ``workspace_context`` — or ``None``
         if the directory is not a valid Azure DevOps git repo.
+
     """
     try:
         result = subprocess.run(
@@ -77,7 +80,8 @@ def inspect_git_repository(repo_path: str) -> dict[str, Any] | None:
 
 
 def discover_repositories(search_root: str) -> list[dict[str, Any]]:
-    """Find all Azure DevOps git repositories under *search_root*.
+    """
+    Find all Azure DevOps git repositories under *search_root*.
 
     If *search_root* itself is a git repository, returns a single-element
     list.  Otherwise scans its immediate children for ``.git`` folders.
@@ -87,6 +91,7 @@ def discover_repositories(search_root: str) -> list[dict[str, Any]]:
 
     Returns:
         A (possibly empty) list of repository info dicts.
+
     """
     repositories: list[dict[str, Any]] = []
 
@@ -115,7 +120,8 @@ def infer_target_repository(
     repositories: list[dict[str, Any]],
     working_directory: str | None = None,
 ) -> dict[str, Any] | None:
-    """Select the most likely target repository from a list.
+    """
+    Select the most likely target repository from a list.
 
     Selection strategy (first match wins):
 
@@ -132,6 +138,7 @@ def infer_target_repository(
 
     Returns:
         The best-guess repository, or ``None`` when the choice is ambiguous.
+
     """
     if not repositories:
         return None

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/iterations.py

@@ -1,4 +1,5 @@
-"""PR iteration tracking and change context resolution.
+"""
+PR iteration tracking and change context resolution.
 
 Provides iteration metadata and per-file change tracking IDs needed for
 anchoring comment threads to the correct PR iteration.
@@ -27,10 +28,12 @@ def get_pr_iterations(
     pr_id: int,
     project: str,
 ) -> list[IterationInfo]:
-    """Return all iterations for a PR, ordered by creation date.
+    """
+    Return all iterations for a PR, ordered by creation date.
 
     Raises:
         ActionableError: When the SDK call fails (connection factory).
+
     """
     try:
         raw_iterations = client.git.get_pull_request_iterations(repository, pr_id, project=project)
@@ -62,7 +65,8 @@ def get_iteration_changes(
     iteration_id: int,
     project: str,
 ) -> list[FileChange]:
-    """Return file changes for a specific iteration with changeTrackingId.
+    """
+    Return file changes for a specific iteration with changeTrackingId.
 
     Uses ``compare_to=0`` (default) which returns all files changed in the
     PR relative to the merge base, not just files changed in this specific
@@ -70,6 +74,7 @@ def get_iteration_changes(
 
     Raises:
         ActionableError: When the SDK call fails (connection factory).
+
     """
     try:
         raw_changes = client.git.get_pull_request_iteration_changes(
@@ -109,7 +114,8 @@ def get_latest_iteration_context(
     pr_id: int,
     project: str,
 ) -> IterationContext:
-    """Convenience: latest iteration ID + file path to FileChange map.
+    """
+    Return the latest iteration context: iteration ID + file path to FileChange map.
 
     Calls :func:`get_pr_iterations` then :func:`get_iteration_changes`
     for the latest iteration. The returned :class:`IterationContext`
@@ -119,6 +125,7 @@ def get_latest_iteration_context(
     Raises:
         ActionableError: When the PR has no iterations (validation) or
             when SDK calls fail (connection).
+
     """
     iterations = get_pr_iterations(client, repository, pr_id, project)
     if not iterations:

{ado_workflows-0.2.2 → ado_workflows-0.3.0}/src/ado_workflows/lifecycle.py

@@ -1,4 +1,5 @@
-"""PR lifecycle operations — create, (future: update, complete).
+"""
+PR lifecycle operations — create, (future: update, complete).
 
 Provides :func:`create_pull_request` which constructs a
 :class:`~azure.devops.v7_1.git.models.GitPullRequest` and delegates to
@@ -41,7 +42,8 @@ def create_pull_request(
     description: str | None = None,
     is_draft: bool = False,
 ) -> CreatedPR:
-    """Create a pull request via the Azure DevOps SDK.
+    """
+    Create a pull request via the Azure DevOps SDK.
 
     Branch names are normalised to include ``refs/heads/`` if missing.
 
@@ -60,6 +62,7 @@ def create_pull_request(
 
     Raises:
         ActionableError: When the SDK call fails.
+
     """
     pr_model = GitPullRequest(
         source_ref_name=_normalize_branch(source_branch),