bmsdna-devtools 0.45.0__tar.gz → 0.47.0__tar.gz

{bmsdna_devtools-0.45.0 → bmsdna_devtools-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.45.0
+Version: 0.47.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: azure-identity>=1.19.0
@@ -19,7 +19,7 @@ Description-Content-Type: text/markdown
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
-one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, finding issues addressed to an agent (`bdt issue search --for-me`) and waiting for new comments (`bdt issue watch`), git worktrees (creation and
+one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, finding issues addressed to an agent (`bdt issue search --for-me`), finding issues filed by business users (`bdt issue search --business-user`) and waiting for new comments (`bdt issue watch`), git worktrees (creation and
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
 pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
 postgres/psycopg (and arrowbricks) SQL rules, pydantic-model placement, hand-wired HTTP access in
@@ -122,7 +122,7 @@ it watches a branch-triggered build/workflow run, not any particular PR.)
 ## `bdt pr info`
 
 ```bash
-bdt pr info [--json] [--pr-id N] [--target-branch BRANCH]
+bdt pr info [--json] [--pr-id PR]... [--target-branch BRANCH] [--all]
 ```
 
 One-shot summary of the current branch's PR: link, state (open/merged/closed, draft), aggregate
@@ -133,6 +133,24 @@ the check rollup (only a failed check fails it; skipped/cancelled ones don't cou
 from the latest build of each pipeline (any failed result fails it; unfinished builds are pending, or
 `waiting` when a stage needs approval). `unknown` if Azure DevOps can't be asked.
 
+`--all` lists every open PR from the current branch (e.g. one into `dev` and one into `main`, which plain
+`bdt pr info` refuses to pick between): with `--json` an array of the same objects, `[]` (exit 0) when there is
+none; `--target-branch` narrows it, `--pr-id` can't be combined with it. Only open PRs are listed, and a PR with
+merge conflicts is listed like any other (plain `pr info` on Azure DevOps errors on it).
+
+`--pr-id` takes several PRs, also of other repos: repeat it and/or comma-separate (`--pr-id 12,34 --pr-id owner/repo#5`).
+Each entry is a bare number (a PR of the current repo), `owner/repo#N` (GitHub), `project/repo#N` or
+`org/project/repo#N` (Azure DevOps; the host is the current repo's, and the org is its org unless given), or the PR's
+URL (GitHub, `dev.azure.com` or `*.visualstudio.com`; the only form that needs no git checkout). One plain number
+behaves as before: the single object. One `owner/repo#N` is a single object too; two or more entries print a list in the
+order given (duplicates once), as `--json` an array like `--all`'s, as text with the repo in each header. A failing entry
+(unknown number, no access) doesn't hide the others: it is reported as `error: <entry>: <reason>` on stderr, the rest is
+still printed, and the exit code is 1. An unreadable entry is a usage error before anything is looked up. `--pr-id` can't
+be combined with `--all`; `--target-branch` is ignored for it, as before. Azure DevOps entries use one PAT/`az login` for
+every org, and a PR with merge conflicts is an error entry there.
+
+Every JSON object has a `repo` (`owner/repo` on GitHub, `org/project/repo` on Azure DevOps).
+
 Azure DevOps limits: the PR is found by the current branch (into `--target-branch` if given, else any target),
 a PR with merge conflicts is reported as an error (exit 1) like `pr status` does, and the closed
 work items are only those whose URL is in the PR description -- not ones linked via
@@ -290,8 +308,7 @@ bdt pr comment --message "Looks good" [--screenshot shot.png] [--file report.pdf
 bdt pr comment --message-file plan.md          # post a file's text as the comment (`-` = stdin)
 ```
 
-`--file` links the file as an *attachment* (a download link in the comment); it does not post the file's
-content. To post a markdown document (an implementation plan, review findings) use `--message-file`.
+Use `--message-file` to post a markdown document (an implementation plan, review findings) as the comment.
 
 ## `bdt issue create` / `show` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
 
@@ -316,8 +333,10 @@ adds/edits/deletes comments on one, auto-detected from `origin` like `bdt pr
 `issue show NUMBER` prints one issue / work item: state, title, URL, description, tags, links to other
 issues (parent, children, blocked by, blocks; related on Azure DevOps), the Azure DevOps Type / Area /
 Iteration / Assigned to (GitHub: assignees, milestone) and all comments (Azure DevOps HTML is shown as plain
-text). `--json` prints the same as one JSON document (`number, title, state, url, body, tags, fields,
-parent, children, blocked_by, blocks, related, comments`).
+text). On Azure DevOps it also prints `Created by:` with whether the creator is a business user (see
+[`bdt issue search --business-user`](#bdt-issue-search---business-user)). `--json` prints the same as one JSON
+document (`number, title, state, url, body, tags, fields, parent, children, blocked_by, blocks, related,
+comments, created_by, business_user, business_user_reason`; the last three are `null` on GitHub).
 
 `--parent ID` and `--blocked-by ID` (repeatable) on `create` and `update` link the item to its parent and to
 the issues / work items that block it, on both backends. On `update` only the links that are missing are
@@ -519,6 +538,33 @@ bdt issue watch 84 --since-comment 123 --skip-own --json --timeout 1800
 - A single failed poll (network blip, API error) is retried; three in a row abort with the error.
 - On Azure DevOps only the newest 100 comments of a work item are looked at per poll.
 
+## `bdt issue search --business-user`
+
+Business users file work items too, often with vague wording, and those need a different handling than a
+developer's. `--business-user` (Azure DevOps only) keeps the work items **created by a business user**:
+
+```bash
+bdt issue search --business-user [--commit-depth 1000] [--tag needs-techie] [--for-me] [--state open] ...
+bdt issue show 1234        # also prints: Created by: Sam Sales (business user: Stakeholder license)
+```
+
+A creator is a business user when
+
+1. their license is **Stakeholder** (Member Entitlement API; needs a PAT with the *Member Entitlement
+   Management (read)* scope), or
+2. they authored **none of the last `--commit-depth` commits** (default 1000) of the repo you run `bdt` in. This
+   also decides when the license can't be read (missing PAT scope, ...) -- the license is then "unknown"; it is
+   not an error.
+
+The commit check matches the creator's email, else display name (a heuristic: two people sharing a name are
+taken for one), against the authors and committers of those commits (`.mailmap` applied). Identities that are
+not a person (build service, service accounts: no email as `uniqueName`) stay "unknown". A developer whose last commit is older than that window, or who works in other
+repos, counts as a business user here. A shallow clone with less history than `--commit-depth` can't say who never
+committed, so the creator stays "unknown" and is not returned by `--business-user`. `issue show` prints the reason
+next to the creator -- `business user`, `developer` or `unknown` -- and `--json` has `created_by`, `business_user`
+and `business_user_reason`. `--business-user` can't be combined with `--org-wide` (the commit check is about this
+repo's history).
+
 ## `bdt env get-keys`
 
 Lists the variable **names** (never the values) defined in `.env`, `*.env` and `.env.*` files under the

{bmsdna_devtools-0.45.0 → bmsdna_devtools-0.47.0}/README.md

@@ -1,7 +1,7 @@
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
-one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, finding issues addressed to an agent (`bdt issue search --for-me`) and waiting for new comments (`bdt issue watch`), git worktrees (creation and
+one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, finding issues addressed to an agent (`bdt issue search --for-me`), finding issues filed by business users (`bdt issue search --business-user`) and waiting for new comments (`bdt issue watch`), git worktrees (creation and
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
 pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
 postgres/psycopg (and arrowbricks) SQL rules, pydantic-model placement, hand-wired HTTP access in
@@ -104,7 +104,7 @@ it watches a branch-triggered build/workflow run, not any particular PR.)
 ## `bdt pr info`
 
 ```bash
-bdt pr info [--json] [--pr-id N] [--target-branch BRANCH]
+bdt pr info [--json] [--pr-id PR]... [--target-branch BRANCH] [--all]
 ```
 
 One-shot summary of the current branch's PR: link, state (open/merged/closed, draft), aggregate
@@ -115,6 +115,24 @@ the check rollup (only a failed check fails it; skipped/cancelled ones don't cou
 from the latest build of each pipeline (any failed result fails it; unfinished builds are pending, or
 `waiting` when a stage needs approval). `unknown` if Azure DevOps can't be asked.
 
+`--all` lists every open PR from the current branch (e.g. one into `dev` and one into `main`, which plain
+`bdt pr info` refuses to pick between): with `--json` an array of the same objects, `[]` (exit 0) when there is
+none; `--target-branch` narrows it, `--pr-id` can't be combined with it. Only open PRs are listed, and a PR with
+merge conflicts is listed like any other (plain `pr info` on Azure DevOps errors on it).
+
+`--pr-id` takes several PRs, also of other repos: repeat it and/or comma-separate (`--pr-id 12,34 --pr-id owner/repo#5`).
+Each entry is a bare number (a PR of the current repo), `owner/repo#N` (GitHub), `project/repo#N` or
+`org/project/repo#N` (Azure DevOps; the host is the current repo's, and the org is its org unless given), or the PR's
+URL (GitHub, `dev.azure.com` or `*.visualstudio.com`; the only form that needs no git checkout). One plain number
+behaves as before: the single object. One `owner/repo#N` is a single object too; two or more entries print a list in the
+order given (duplicates once), as `--json` an array like `--all`'s, as text with the repo in each header. A failing entry
+(unknown number, no access) doesn't hide the others: it is reported as `error: <entry>: <reason>` on stderr, the rest is
+still printed, and the exit code is 1. An unreadable entry is a usage error before anything is looked up. `--pr-id` can't
+be combined with `--all`; `--target-branch` is ignored for it, as before. Azure DevOps entries use one PAT/`az login` for
+every org, and a PR with merge conflicts is an error entry there.
+
+Every JSON object has a `repo` (`owner/repo` on GitHub, `org/project/repo` on Azure DevOps).
+
 Azure DevOps limits: the PR is found by the current branch (into `--target-branch` if given, else any target),
 a PR with merge conflicts is reported as an error (exit 1) like `pr status` does, and the closed
 work items are only those whose URL is in the PR description -- not ones linked via
@@ -272,8 +290,7 @@ bdt pr comment --message "Looks good" [--screenshot shot.png] [--file report.pdf
 bdt pr comment --message-file plan.md          # post a file's text as the comment (`-` = stdin)
 ```
 
-`--file` links the file as an *attachment* (a download link in the comment); it does not post the file's
-content. To post a markdown document (an implementation plan, review findings) use `--message-file`.
+Use `--message-file` to post a markdown document (an implementation plan, review findings) as the comment.
 
 ## `bdt issue create` / `show` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
 
@@ -298,8 +315,10 @@ adds/edits/deletes comments on one, auto-detected from `origin` like `bdt pr
 `issue show NUMBER` prints one issue / work item: state, title, URL, description, tags, links to other
 issues (parent, children, blocked by, blocks; related on Azure DevOps), the Azure DevOps Type / Area /
 Iteration / Assigned to (GitHub: assignees, milestone) and all comments (Azure DevOps HTML is shown as plain
-text). `--json` prints the same as one JSON document (`number, title, state, url, body, tags, fields,
-parent, children, blocked_by, blocks, related, comments`).
+text). On Azure DevOps it also prints `Created by:` with whether the creator is a business user (see
+[`bdt issue search --business-user`](#bdt-issue-search---business-user)). `--json` prints the same as one JSON
+document (`number, title, state, url, body, tags, fields, parent, children, blocked_by, blocks, related,
+comments, created_by, business_user, business_user_reason`; the last three are `null` on GitHub).
 
 `--parent ID` and `--blocked-by ID` (repeatable) on `create` and `update` link the item to its parent and to
 the issues / work items that block it, on both backends. On `update` only the links that are missing are
@@ -501,6 +520,33 @@ bdt issue watch 84 --since-comment 123 --skip-own --json --timeout 1800
 - A single failed poll (network blip, API error) is retried; three in a row abort with the error.
 - On Azure DevOps only the newest 100 comments of a work item are looked at per poll.
 
+## `bdt issue search --business-user`
+
+Business users file work items too, often with vague wording, and those need a different handling than a
+developer's. `--business-user` (Azure DevOps only) keeps the work items **created by a business user**:
+
+```bash
+bdt issue search --business-user [--commit-depth 1000] [--tag needs-techie] [--for-me] [--state open] ...
+bdt issue show 1234        # also prints: Created by: Sam Sales (business user: Stakeholder license)
+```
+
+A creator is a business user when
+
+1. their license is **Stakeholder** (Member Entitlement API; needs a PAT with the *Member Entitlement
+   Management (read)* scope), or
+2. they authored **none of the last `--commit-depth` commits** (default 1000) of the repo you run `bdt` in. This
+   also decides when the license can't be read (missing PAT scope, ...) -- the license is then "unknown"; it is
+   not an error.
+
+The commit check matches the creator's email, else display name (a heuristic: two people sharing a name are
+taken for one), against the authors and committers of those commits (`.mailmap` applied). Identities that are
+not a person (build service, service accounts: no email as `uniqueName`) stay "unknown". A developer whose last commit is older than that window, or who works in other
+repos, counts as a business user here. A shallow clone with less history than `--commit-depth` can't say who never
+committed, so the creator stays "unknown" and is not returned by `--business-user`. `issue show` prints the reason
+next to the creator -- `business user`, `developer` or `unknown` -- and `--json` has `created_by`, `business_user`
+and `business_user_reason`. `--business-user` can't be combined with `--org-wide` (the commit check is about this
+repo's history).
+
 ## `bdt env get-keys`
 
 Lists the variable **names** (never the values) defined in `.env`, `*.env` and `.env.*` files under the

{bmsdna_devtools-0.45.0 → bmsdna_devtools-0.47.0}/bmsdna/devtools/ado_issue.py

@@ -50,6 +50,7 @@ from urllib.parse import quote
 import requests
 
 from .bdt_config import load_bdt_table
+from .business_user import BusinessUserDetector
 from .cli_tools import ensure_agent_session_note
 from .gitrepo import AdoRemote
 from .issue_show import IssueDetails
@@ -324,9 +325,12 @@ def get_work_item(session: requests.Session, remote: AdoRemote, work_item_id: in
     return r.json()
 
 
-def get_details(session: requests.Session, remote: AdoRemote, work_item_id: int) -> IssueDetails:
+def get_details(
+    session: requests.Session, remote: AdoRemote, work_item_id: int, business_users: BusinessUserDetector | None = None
+) -> IssueDetails:
     """What `bdt issue show` prints for a work item: its fields, links and comments. Long text
-    (Description, comments) is HTML as stored; it is shown as plain text."""
+    (Description, comments) is HTML as stored; it is shown as plain text. With `business_users`, also who
+    created it and whether that is a business user."""
     work_item = get_work_item(session, remote, work_item_id)
     fields = work_item.get("fields", {})
     relations = work_item.get("relations") or []
@@ -338,6 +342,8 @@ def get_details(session: requests.Session, remote: AdoRemote, work_item_id: int)
     if isinstance(assigned_to, dict):
         assigned_to = assigned_to.get("displayName")
     parents = linked(PARENT_REL)
+    creator = fields.get("System.CreatedBy")
+    verdict = business_users.verdict(creator) if business_users else None
     return IssueDetails(
         number=work_item_id,
         title=fields.get("System.Title", ""),
@@ -357,6 +363,9 @@ def get_details(session: requests.Session, remote: AdoRemote, work_item_id: int)
         blocks=linked(BLOCKS_REL),
         related=linked(RELATED_REL),
         comments=to_comments(list_all_comments(session, remote, work_item_id), is_html=True),
+        created_by=creator.get("displayName") if isinstance(creator, dict) else None,
+        business_user=verdict.business_user if verdict else None,
+        business_user_reason=verdict.reason if verdict else None,
     )
 
 
@@ -700,7 +709,9 @@ def run_wiql(session: requests.Session, remote: AdoRemote, wiql: str, top: int,
     return [wi["id"] for wi in r.json()["workItems"]]
 
 
-def get_work_items(session: requests.Session, remote: AdoRemote, ids: list[int], org_wide: bool = False) -> list[dict]:
+def get_work_items(
+    session: requests.Session, remote: AdoRemote, ids: list[int], org_wide: bool = False, with_creator: bool = False
+) -> list[dict]:
     """Batch-fetch Title/State (plus TeamProject when `org_wide`) for a set of work item ids, in
     the given `ids` order — WIQL only returns ids (not field values), and this batch endpoint
     doesn't guarantee it echoes them back in the order they were requested, so the caller's WIQL
@@ -708,12 +719,14 @@ def get_work_items(session: requests.Session, remote: AdoRemote, ids: list[int],
 
     `org_wide` fetches via the org-level endpoint (ids from an org-wide `run_wiql` may belong to
     a project other than `remote.project`) and also asks for `System.TeamProject`, so `search()`
-    can show which project each result came from.
+    can show which project each result came from. `with_creator` also asks for `System.CreatedBy`.
     """
     if not ids:
         return []
     base = _org_url(remote) if org_wide else _base_url(remote)
     fields = "System.Title,System.State,System.TeamProject" if org_wide else "System.Title,System.State"
+    if with_creator:
+        fields += ",System.CreatedBy"
     r = session.get(
         f"{base}/_apis/wit/workitems",
         params={"ids": ",".join(map(str, ids)), "fields": fields, "api-version": "7.1"},
@@ -756,6 +769,7 @@ def search(
     tags: list[str] | None = None,
     comment_filter: Callable[[str | None], bool] | None = None,
     scan_limit: int | None = None,
+    business_users: BusinessUserDetector | None = None,
 ) -> 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
@@ -771,13 +785,21 @@ def search(
     e.g. `bdt issue search --for-me`. WIQL can't query comments, so up to `_COMMENT_FILTER_POOL`
     candidates are fetched and checked one by one, stopping once `top` have matched. `scan_limit` sizes that
     pool as if it were `top` (default: `top`), for a caller that wants few results out of a wide scan.
+
+    `business_users` keeps only work items created by a business user (see `business_user.py`), checked before
+    `comment_filter` since it costs no request per work item.
     """
     if org_wide and board:
         sys.exit("--board can't be combined with --org-wide (a board's Area Path is scoped to a single project).")
     area_path = get_team_area_path(session, remote, board) if board else None
     wiql = build_search_wiql(keywords, since, area_path, state, org_wide=org_wide, tags=tags)
-    ids = run_wiql(session, remote, wiql, min((scan_limit or top) * 10, _COMMENT_FILTER_POOL) if comment_filter else top, org_wide=org_wide)
-    items = get_work_items(session, remote, ids, org_wide=org_wide)
+    filtered = comment_filter or business_users
+    ids = run_wiql(session, remote, wiql, min((scan_limit or top) * 10, _COMMENT_FILTER_POOL) if filtered else top, org_wide=org_wide)
+    items = get_work_items(session, remote, ids, org_wide=org_wide, with_creator=business_users is not None)
+    if business_users:
+        items = [i for i in items if business_users.verdict(i["fields"].get("System.CreatedBy")).business_user]
+        if not comment_filter:
+            items = items[:top]
     if comment_filter:
         items = _filter_by_last_comment(session, remote, items, top, comment_filter)
     for item in items:

bmsdna_devtools-0.47.0/bmsdna/devtools/business_user.py

@@ -0,0 +1,144 @@
+"""Is the creator of an Azure DevOps work item a business user (as opposed to a developer)?
+
+Backs `bdt issue search --business-user` and the `Created by` line of `bdt issue show`. A creator is a
+business user when
+
+1. their Azure DevOps license is `Stakeholder` (Member Entitlement API), or
+2. they authored none of the last `DEFAULT_COMMIT_DEPTH` commits of the local repo.
+
+The entitlement API needs a PAT with the "Member Entitlement Management (read)" scope; when it is not
+reachable the license is treated as unknown and only the commit check decides.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+from urllib.parse import quote
+
+import requests
+
+from .gitrepo import AdoRemote
+
+DEFAULT_COMMIT_DEPTH = 1000
+STAKEHOLDER = "stakeholder"
+_ENTITLEMENT_API_VERSION = "7.1-preview.3"
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """`business_user` is None when neither check could tell (no license info, no usable git history)."""
+
+    business_user: bool | None
+    reason: str
+
+
+@dataclass(frozen=True)
+class CommitAuthors:
+    """Lowercased emails and names of the authors and committers of the last `depth` commits."""
+
+    emails: frozenset[str]
+    names: frozenset[str]
+    depth: int
+
+    def contains(self, email: str | None, name: str | None) -> bool:
+        return bool(email and email.casefold() in self.emails) or bool(name and name.casefold() in self.names)
+
+
+def read_commit_authors(depth: int = DEFAULT_COMMIT_DEPTH, cwd: Path | None = None) -> CommitAuthors | None:
+    """The authors of the last `depth` commits of the repo at `cwd`, or None when that history can't tell who never
+    committed: not a git repo, or a shallow clone that has fewer than `depth` commits."""
+    # %aE/%aN/%cE/%cN honour .mailmap; \x1f can't occur in a name, and a name can't hold a newline
+    log = subprocess.run(
+        ["git", "log", "-n", str(depth), "--format=%aE%x1f%aN%x1f%cE%x1f%cN"],
+        capture_output=True,
+        encoding="utf-8",
+        errors="replace",
+        cwd=cwd,
+        check=False,
+    )
+    if log.returncode != 0:
+        return None
+    rows = [fields for line in log.stdout.split("\n") if len(fields := line.split("\x1f")) == 4]
+    # `--is-shallow-repository` needs git 2.15; the shallow file's presence works everywhere
+    shallow_file = subprocess.run(["git", "rev-parse", "--git-path", "shallow"], capture_output=True, text=True, cwd=cwd, check=False)
+    if shallow_file.returncode == 0 and (cwd or Path()).joinpath(shallow_file.stdout.strip()).exists() and len(rows) < depth:
+        return None
+    return CommitAuthors(
+        emails=frozenset(v.casefold() for row in rows for v in (row[0], row[2]) if v),
+        names=frozenset(v.casefold() for row in rows for v in (row[1], row[3]) if v),
+        depth=depth,
+    )
+
+
+def get_license(session: requests.Session, remote: AdoRemote, identity_id: str) -> str | None:
+    """The account license type of an identity, lowercased (`stakeholder`, `express`, `advanced`, `none`, ...), or None
+    when the entitlement API doesn't answer (missing PAT scope, user not in the org, outage, ...): the license is
+    optional enrichment, and the commit check still has a say without it."""
+    try:
+        r = session.get(
+            f"https://vsaex.dev.azure.com/{remote.org}/_apis/userentitlements/{quote(identity_id, safe='')}",
+            params={"api-version": _ENTITLEMENT_API_VERSION},
+        )
+    except requests.RequestException:
+        return None
+    if r.status_code != 200:
+        return None
+    try:
+        body = r.json()
+    except ValueError:  # e.g. an HTML sign-in page for a PAT that may not use this API
+        return None
+    license_type = ((body.get("accessLevel") if isinstance(body, dict) else None) or {}).get("accountLicenseType")
+    return license_type.casefold() if isinstance(license_type, str) else None
+
+
+def classify(
+    license_type: str | None, read_authors: Callable[[], CommitAuthors | None], email: str | None, name: str | None
+) -> Verdict:
+    """Stakeholder license -> business user; else, no commit by this person in `read_authors()` (only called when the
+    license doesn't settle it) -> business user."""
+    if license_type == STAKEHOLDER:
+        return Verdict(True, "Stakeholder license")
+    authors = read_authors()
+    known_license = f"{license_type} license" if license_type else "license unknown"
+    if authors is None:
+        return Verdict(None, f"{known_license}, commit history unavailable")
+    if authors.contains(email, name):
+        return Verdict(False, f"{known_license}, has commits")
+    return Verdict(True, f"{known_license}, no commits in the last {authors.depth} of this repo")
+
+
+class BusinessUserDetector:
+    """Judges work item creators (the `System.CreatedBy` identity dict), looking up each license once and reading
+    the git history of the current directory's repo once per detector."""
+
+    def __init__(self, session: requests.Session, remote: AdoRemote, commit_depth: int = DEFAULT_COMMIT_DEPTH) -> None:
+        self._session = session
+        self._remote = remote
+        self._commit_depth = commit_depth
+        self._licenses: dict[str, str | None] = {}
+
+    @cached_property
+    def _commit_authors(self) -> CommitAuthors | None:
+        return read_commit_authors(self._commit_depth)
+
+    def _license(self, identity_id: str | None) -> str | None:
+        if not identity_id:
+            return None
+        if identity_id not in self._licenses:
+            self._licenses[identity_id] = get_license(self._session, self._remote, identity_id)
+        return self._licenses[identity_id]
+
+    def verdict(self, creator: dict | None) -> Verdict:
+        """`creator` is the `System.CreatedBy` field: an identity dict (`id`, `uniqueName`, `displayName`)."""
+        if not isinstance(creator, dict):
+            return Verdict(None, "creator unknown")
+        if "@" not in (creator.get("uniqueName") or ""):
+            # build service, service accounts, ...: no license, no commits, and not someone to ask questions
+            return Verdict(None, "not a person")
+        identity_id = creator.get("id")
+        license_type = self._license(identity_id if isinstance(identity_id, str) else None)
+        return classify(license_type, lambda: self._commit_authors, creator.get("uniqueName"), creator.get("displayName"))