bmsdna-devtools 0.7.0__tar.gz → 0.8.0__tar.gz

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.7.0
+Version: 0.8.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.11
 Requires-Dist: requests>=2.32.0

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/bmsdna/devtools/ado_issue.py

@@ -264,6 +264,106 @@ def html_url(work_item: dict) -> str | None:
     return work_item.get("_links", {}).get("html", {}).get("href")
 
 
+def edit_url(remote: AdoRemote, work_item_id: int) -> str:
+    return f"{_base_url(remote)}/_workitems/edit/{work_item_id}"
+
+
+def _escape_wiql_string(value: str) -> str:
+    return value.replace("'", "''")
+
+
+# The Completed/Removed-category state names across Azure DevOps's built-in process templates:
+# Agile and CMMI use 'Closed' for Completed, Scrum and Basic use 'Done'; all four use 'Removed'.
+# There's no single field/value that means "terminal" independent of process template, so this
+# union is the closest thing to a default that works out of the box on any of them.
+_TERMINAL_STATES = ("Closed", "Done", "Removed")
+
+
+def build_search_wiql(
+    keywords: list[str],
+    since: str | None = None,
+    area_path: str | None = None,
+    state: str = "open",
+) -> str:
+    """WIQL for work items whose Title or Description contains every given keyword (ANDed),
+    optionally restricted to items changed on/after `since` (an ISO 'YYYY-MM-DD' date) and/or
+    scoped to a board's Area Path subtree, most recently changed first. `keywords` may be empty,
+    to list work items without a text filter.
+
+    `since` is rendered as a UTC ISO 8601 literal (`'YYYY-MM-DDT00:00:00Z'`) — the one
+    DateTime format WIQL accepts regardless of the querying account's locale/date-pattern
+    preference (a bare `'YYYY-MM-DD'` is parsed using that locale's date pattern instead).
+
+    `state` is `"open"` (default, excludes `_TERMINAL_STATES`), `"closed"` (only those), or
+    `"all"` (no state filter). Azure DevOps state names are process-template-specific — Agile and
+    CMMI use 'Closed' for their Completed-category state, Scrum and Basic use 'Done' — so
+    `_TERMINAL_STATES` is the union across the built-in templates, not a per-project source of
+    truth (a custom process with its own state names won't be filtered correctly).
+    """
+    clauses = [
+        f"([System.Title] Contains Words '{_escape_wiql_string(k)}' OR [System.Description] Contains Words '{_escape_wiql_string(k)}')"
+        for k in keywords
+    ]
+    if since:
+        clauses.append(f"[System.ChangedDate] >= '{since}T00:00:00Z'")
+    if area_path:
+        clauses.append(f"[System.AreaPath] UNDER '{_escape_wiql_string(area_path)}'")
+    if state == "open":
+        clauses.append(" AND ".join(f"[System.State] <> '{s}'" for s in _TERMINAL_STATES))
+    elif state == "closed":
+        clauses.append("(" + " OR ".join(f"[System.State] = '{s}'" for s in _TERMINAL_STATES) + ")")
+    where = " AND ".join(["[System.TeamProject] = @project", *clauses])
+    return f"SELECT [System.Id] FROM WorkItems WHERE {where} ORDER BY [System.ChangedDate] DESC"
+
+
+def run_wiql(session: requests.Session, remote: AdoRemote, wiql: str, top: int) -> list[int]:
+    r = session.post(
+        f"{_base_url(remote)}/_apis/wit/wiql",
+        params={"api-version": "7.1", "$top": top},
+        json={"query": wiql},
+    )
+    r.raise_for_status()
+    return [wi["id"] for wi in r.json()["workItems"]]
+
+
+def get_work_items(session: requests.Session, remote: AdoRemote, ids: list[int]) -> list[dict]:
+    """Batch-fetch Title/State for a set of work item ids. WIQL only returns ids, not field values."""
+    if not ids:
+        return []
+    r = session.get(
+        f"{_base_url(remote)}/_apis/wit/workitems",
+        params={"ids": ",".join(map(str, ids)), "fields": "System.Title,System.State", "api-version": "7.1"},
+    )
+    r.raise_for_status()
+    return r.json()["value"]
+
+
+def search(
+    session: requests.Session,
+    remote: AdoRemote,
+    keywords: list[str],
+    since: str | None = None,
+    board: str | None = None,
+    top: int = 10,
+    state: str = "open",
+) -> list[dict]:
+    """Search (or, with no keywords, just list) work items by keywords (ANDed, matched against
+    Title or Description) and state, most recently changed first. `board` is an Azure Boards team
+    name (like `create`'s `--board`) — resolved to its Area Path so results are scoped to that
+    team's subtree instead of the whole project.
+    """
+    area_path = get_team_area_path(session, remote, board) if board else None
+    ids = run_wiql(session, remote, build_search_wiql(keywords, since, area_path, state), top)
+    items = get_work_items(session, remote, ids)
+    for item in items:
+        fields = item["fields"]
+        print(f"#{item['id']} [{fields['System.State']}] {fields['System.Title']}")
+        print(edit_url(remote, item["id"]))
+    if not items:
+        print("No matching work items found.")
+    return items
+
+
 def create(
     session: requests.Session,
     remote: AdoRemote,

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/bmsdna/devtools/cli.py

@@ -4,6 +4,7 @@ import json
 import subprocess
 import sys
 from collections.abc import Callable
+from datetime import datetime, timedelta, timezone
 from importlib.metadata import version as _pkg_version
 from pathlib import Path
 
@@ -325,6 +326,46 @@ def issue_create(
         ado_issue.create(session, remote, type_, title, description, resolved_board, tag, screenshot)
 
 
+@issue_app.command("search")
+def issue_search(
+    keywords: list[str] = typer.Argument(
+        None, help="Keywords to search for (ANDed together); omit to just list issues/work items"
+    ),
+    since_days: int = typer.Option(
+        30, "--since-days", help="Only include issues/work items updated within this many days (0 = no date filter)"
+    ),
+    state: str = typer.Option("open", "--state", help="Filter by state: 'open', 'closed', or 'all'"),
+    board: str | None = typer.Option(
+        None,
+        "--board",
+        help="Scope the search to this Azure Boards team's Area Path subtree (Azure DevOps only; "
+        r"falls back to \[tool.bdt.ado].board in pyproject.toml, same as `issue create`)",
+    ),
+    limit: int = typer.Option(10, "--limit", help="Max results to return"),
+    pat: str | None = typer.Option(
+        None,
+        "--pat",
+        envvar=["AZURE_DEVOPS_EXT_PAT", "AZURE_DEVOPS_PAT"],
+        help="Azure DevOps PAT (else falls back to `az` login)",
+    ),
+) -> None:
+    """Search (or, with no keywords, just list) issues / work items, defaulting to open issues
+    from the last 30 days (Azure DevOps or GitHub, auto-detected).
+    """
+    if state not in ("open", "closed", "all"):
+        raise typer.BadParameter("Must be one of: open, closed, all", param_hint="--state")
+    since = (datetime.now(timezone.utc) - timedelta(days=since_days)).strftime("%Y-%m-%d") if since_days > 0 else None
+
+    remote = current_remote()
+    if isinstance(remote, GitHubRemote):
+        gh_issue.search(require_gh(), keywords or [], since, limit, state)
+    else:
+        session = requests.Session()
+        session.headers.update(auth_header(pat))
+        resolved_board = ado_issue.resolve_board(board)
+        ado_issue.search(session, remote, keywords or [], since=since, board=resolved_board, top=limit, state=state)
+
+
 @issue_app.command("update")
 def issue_update(
     number: int = typer.Argument(..., help="Issue number (GitHub) or work item ID (Azure DevOps)"),

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/bmsdna/devtools/gh_issue.py

@@ -18,6 +18,7 @@ hosts).
 
 from __future__ import annotations
 
+import json
 import re
 import subprocess
 import sys
@@ -81,6 +82,35 @@ def create(
         print(f"Attached {len(screenshot_paths)} screenshot(s) to issue #{number}")
 
 
+def build_search_query(keywords: list[str], since: str | None) -> str:
+    """The `gh issue list --search` query string: keywords ANDed together (GitHub search's
+    implicit default), optionally scoped to issues updated on/after `since` (an ISO
+    'YYYY-MM-DD' date) via the `updated:` qualifier. Always sorted `updated:desc` — GitHub's
+    default search order is text-relevance, not recency, which `search()`'s ordering relies on.
+    `keywords` may be empty, to list issues without a text filter.
+    """
+    parts = [*keywords, "sort:updated-desc"]
+    if since:
+        parts.append(f"updated:>={since}")
+    return " ".join(parts)
+
+
+def search(gh: str, keywords: list[str], since: str | None, limit: int, state: str = "open") -> list[dict]:
+    """Search (or, with no keywords, just list) issues by state, most recently updated first.
+
+    `state` is `gh issue list`'s own `open|closed|all` flag, not a search qualifier.
+    """
+    query = build_search_query(keywords, since)
+    out = _run_gh(gh, ["issue", "list", "--search", query, "--state", state, "--limit", str(limit), "--json", "number,title,url,state"])
+    items = json.loads(out) if out else []
+    for item in items:
+        print(f"#{item['number']} [{item['state']}] {item['title']}")
+        print(item["url"])
+    if not items:
+        print("No matching issues found.")
+    return items
+
+
 def update(
     gh: str,
     number: int,

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/pyproject.toml

@@ -10,7 +10,7 @@ packages = ["bmsdna"]
 
 [project]
 name = "bmsdna-devtools"
-version = "0.7.0"
+version = "0.8.0"
 description = "Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects"
 readme = "README.md"
 requires-python = ">=3.11"

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/tests/test_ado_issue.py

@@ -1,4 +1,13 @@
-from bmsdna.devtools.ado_issue import build_attach_ops, build_create_ops, build_update_ops, html_url, resolve_board
+from bmsdna.devtools.ado_issue import (
+    build_attach_ops,
+    build_create_ops,
+    build_search_wiql,
+    build_update_ops,
+    edit_url,
+    html_url,
+    resolve_board,
+)
+from bmsdna.devtools.gitrepo import AdoRemote
 
 
 def write_pyproject(tmp_path, body: str):
@@ -91,3 +100,66 @@ def test_html_url_present() -> None:
 
 def test_html_url_missing() -> None:
     assert html_url({}) is None
+
+
+def test_edit_url() -> None:
+    assert edit_url(AdoRemote(org="myorg", project="MyProj", repo="myrepo"), 42) == "https://dev.azure.com/myorg/MyProj/_workitems/edit/42"
+
+
+def test_build_search_wiql_keywords_only() -> None:
+    wiql = build_search_wiql(["auth"], state="all")
+    assert "[System.TeamProject] = @project" in wiql
+    assert "[System.Title] Contains Words 'auth'" in wiql
+    assert "[System.Description] Contains Words 'auth'" in wiql
+    assert "[System.ChangedDate] >=" not in wiql
+    assert wiql.endswith("ORDER BY [System.ChangedDate] DESC")
+
+
+def test_build_search_wiql_no_keywords_lists_without_text_filter() -> None:
+    wiql = build_search_wiql([], state="all")
+    assert wiql == "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project ORDER BY [System.ChangedDate] DESC"
+
+
+def test_build_search_wiql_defaults_to_open_state() -> None:
+    # Covers all four built-in process templates' terminal state names (Agile/CMMI: 'Closed',
+    # Scrum/Basic: 'Done'; all: 'Removed') since search() doesn't know which one a project uses.
+    wiql = build_search_wiql(["auth"])
+    assert "[System.State] <> 'Closed'" in wiql
+    assert "[System.State] <> 'Done'" in wiql
+    assert "[System.State] <> 'Removed'" in wiql
+
+
+def test_build_search_wiql_closed_state() -> None:
+    wiql = build_search_wiql(["auth"], state="closed")
+    assert "[System.State] = 'Closed'" in wiql
+    assert "[System.State] = 'Done'" in wiql
+    assert "[System.State] = 'Removed'" in wiql
+    assert "<>" not in wiql
+
+
+def test_build_search_wiql_all_state_has_no_state_clause() -> None:
+    assert "System.State" not in build_search_wiql(["auth"], state="all")
+
+
+def test_build_search_wiql_multiple_keywords_are_anded() -> None:
+    wiql = build_search_wiql(["auth", "timeout"], state="all")
+    assert wiql.count(" AND ") == 2  # TeamProject AND keyword1 AND keyword2
+
+
+def test_build_search_wiql_since_adds_changed_date_clause() -> None:
+    wiql = build_search_wiql(["auth"], since="2026-08-10")
+    assert "[System.ChangedDate] >= '2026-08-10T00:00:00Z'" in wiql
+
+
+def test_build_search_wiql_escapes_single_quotes() -> None:
+    wiql = build_search_wiql(["it's broken"])
+    assert "it''s broken" in wiql
+
+
+def test_build_search_wiql_area_path_scopes_to_board() -> None:
+    wiql = build_search_wiql(["auth"], area_path="MyProj\\Data Team")
+    assert "[System.AreaPath] UNDER 'MyProj\\Data Team'" in wiql
+
+
+def test_build_search_wiql_no_area_path_by_default() -> None:
+    assert "AreaPath" not in build_search_wiql(["auth"])

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/tests/test_ado_issue_flow.py

@@ -13,6 +13,7 @@ from bmsdna.devtools.ado_issue import (
     create,
     delete,
     delete_comment,
+    search,
     update,
     update_comment,
 )
@@ -34,7 +35,7 @@ class FakeResponse:
             raise RuntimeError(f"HTTP {self.status_code}")
 
 
-def make_session(get_map: dict[str, dict] | None = None) -> MagicMock:
+def make_session(get_map: dict[str, dict] | None = None, wiql_ids: list[int] | None = None) -> MagicMock:
     session = MagicMock()
     get_map = get_map or {}
 
@@ -45,6 +46,8 @@ def make_session(get_map: dict[str, dict] | None = None) -> MagicMock:
         raise AssertionError(f"unexpected GET {url}")
 
     def fake_post(url, params: dict | None = None, **kwargs):
+        if "/_apis/wit/wiql" in url:
+            return FakeResponse({"workItems": [{"id": i} for i in (wiql_ids or [])]})
         if "/_apis/wit/attachments" in url:
             assert params is not None
             name = params["fileName"]
@@ -187,3 +190,59 @@ def test_delete_comment_hits_comment_id_endpoint() -> None:
 
     url = session.delete.call_args.args[0]
     assert url == "https://dev.azure.com/myorg/MyProj/_apis/wit/workItems/42/comments/7"
+
+
+def test_search_runs_wiql_then_batch_fetches_matched_fields() -> None:
+    session = make_session(
+        get_map={"/_apis/wit/workitems": {"value": [{"id": 42, "fields": {"System.Title": "Auth timeout bug", "System.State": "Active"}}]}},
+        wiql_ids=[42],
+    )
+
+    results = search(session, REMOTE, ["auth", "timeout"])
+
+    wiql_url, wiql_kwargs = session.post.call_args_list[0].args[0], session.post.call_args_list[0].kwargs
+    assert wiql_url == "https://dev.azure.com/myorg/MyProj/_apis/wit/wiql"
+    assert "auth" in wiql_kwargs["json"]["query"]
+    assert "timeout" in wiql_kwargs["json"]["query"]
+
+    get_url, get_kwargs = session.get.call_args.args[0], session.get.call_args.kwargs
+    assert get_url == "https://dev.azure.com/myorg/MyProj/_apis/wit/workitems"
+    assert get_kwargs["params"]["ids"] == "42"
+
+    assert results == [{"id": 42, "fields": {"System.Title": "Auth timeout bug", "System.State": "Active"}}]
+
+
+def test_search_skips_batch_fetch_when_no_matches() -> None:
+    session = make_session(wiql_ids=[])
+
+    results = search(session, REMOTE, ["nonexistent-keyword"])
+
+    session.get.assert_not_called()
+    assert results == []
+
+
+def test_search_with_board_resolves_area_path_and_scopes_wiql() -> None:
+    session = make_session(
+        get_map={
+            "teamsettings/teamfieldvalues": {"defaultValue": "MyProj\\Data Team"},
+            "/_apis/wit/workitems": {"value": []},
+        },
+        wiql_ids=[],
+    )
+
+    search(session, REMOTE, ["auth"], board="Data Team")
+
+    # Team field values lookup must happen before the WIQL query is built/run.
+    get_url = session.get.call_args_list[0].args[0]
+    assert "myorg/MyProj/Data%20Team/_apis/work/teamsettings/teamfieldvalues" in get_url
+
+    wiql_kwargs = session.post.call_args.kwargs
+    assert "[System.AreaPath] UNDER 'MyProj\\Data Team'" in wiql_kwargs["json"]["query"]
+
+
+def test_search_without_board_does_not_look_up_area_path() -> None:
+    session = make_session(wiql_ids=[])
+
+    search(session, REMOTE, ["auth"])
+
+    session.get.assert_not_called()  # no --board given, so no team field values lookup at all

bmsdna_devtools-0.8.0/tests/test_gh_issue.py

@@ -0,0 +1,72 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from bmsdna.devtools.gh_issue import build_search_query, parse_comment_id, parse_issue_number, search
+
+
+@pytest.mark.parametrize(
+    "url,expected",
+    [
+        ("https://github.com/owner/repo/issues/42", "42"),
+        ("https://github.com/owner/repo/issues/42/", "42"),
+        ("http://github.com/owner/repo/issues/1", "1"),
+    ],
+)
+def test_parse_issue_number(url: str, expected: str) -> None:
+    assert parse_issue_number(url) == expected
+
+
+def test_parse_comment_id_present() -> None:
+    url = "https://github.com/owner/repo/issues/42#issuecomment-123456789"
+    assert parse_comment_id(url) == "123456789"
+
+
+def test_parse_comment_id_absent() -> None:
+    assert parse_comment_id("https://github.com/owner/repo/issues/42") is None
+
+
+def test_build_search_query_keywords_only() -> None:
+    assert build_search_query(["auth", "timeout"], None) == "auth timeout sort:updated-desc"
+
+
+def test_build_search_query_adds_updated_qualifier() -> None:
+    assert build_search_query(["auth"], "2026-08-10") == "auth sort:updated-desc updated:>=2026-08-10"
+
+
+def test_build_search_query_no_keywords_still_scopes_by_date() -> None:
+    assert build_search_query([], "2026-08-10") == "sort:updated-desc updated:>=2026-08-10"
+
+
+def test_build_search_query_always_sorts_by_updated_desc() -> None:
+    # search()'s "most recently updated first" ordering depends on this — GitHub's
+    # default --search order is text relevance, not recency.
+    assert "sort:updated-desc" in build_search_query(["auth"], None)
+
+
+def test_search_defaults_to_open_state(monkeypatch) -> None:
+    captured_cmd: list[str] = []
+
+    def fake_run(cmd, **kwargs):
+        captured_cmd[:] = cmd
+        return MagicMock(returncode=0, stdout="[]", stderr="")
+
+    monkeypatch.setattr("bmsdna.devtools.gh_issue.subprocess.run", fake_run)
+
+    search("gh", [], None, 10)
+
+    assert captured_cmd[captured_cmd.index("--state") + 1] == "open"
+
+
+def test_search_passes_through_requested_state(monkeypatch) -> None:
+    captured_cmd: list[str] = []
+
+    def fake_run(cmd, **kwargs):
+        captured_cmd[:] = cmd
+        return MagicMock(returncode=0, stdout="[]", stderr="")
+
+    monkeypatch.setattr("bmsdna.devtools.gh_issue.subprocess.run", fake_run)
+
+    search("gh", ["auth"], None, 10, state="all")
+
+    assert captured_cmd[captured_cmd.index("--state") + 1] == "all"

{bmsdna_devtools-0.7.0 → bmsdna_devtools-0.8.0}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "bmsdna-devtools"
-version = "0.7.0"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "requests" },

bmsdna_devtools-0.7.0/tests/test_gh_issue.py

@@ -1,24 +0,0 @@
-import pytest
-
-from bmsdna.devtools.gh_issue import parse_comment_id, parse_issue_number
-
-
-@pytest.mark.parametrize(
-    "url,expected",
-    [
-        ("https://github.com/owner/repo/issues/42", "42"),
-        ("https://github.com/owner/repo/issues/42/", "42"),
-        ("http://github.com/owner/repo/issues/1", "1"),
-    ],
-)
-def test_parse_issue_number(url: str, expected: str) -> None:
-    assert parse_issue_number(url) == expected
-
-
-def test_parse_comment_id_present() -> None:
-    url = "https://github.com/owner/repo/issues/42#issuecomment-123456789"
-    assert parse_comment_id(url) == "123456789"
-
-
-def test_parse_comment_id_absent() -> None:
-    assert parse_comment_id("https://github.com/owner/repo/issues/42") is None