@reneturcios/greenlight 0.17.1 → 0.19.0

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import type { IssueSnapshot, LinkedPR, CommentSignal, GateKind, Gate, MentionedPR, DuplicateTarget } from "./types.js";
+import type { IssueSnapshot, LinkedPR, CommentSignal, GateKind, Gate, MentionedPR, DuplicateTarget, PolicySourceProvenance } from "./types.js";
 import { type WorkflowFile } from "./gates.js";
 /**
  * The GitHub API base in use. Reads GREENLIGHT_GITHUB_BASE_URL so a
@@ -44,6 +44,24 @@ export declare function apiCallsUsed(): number;
 /** Reset the call counter (tests). */
 export declare function resetApiCalls(): void;
 export declare function apiGet(path: string): Promise<unknown>;
+export interface CanonicalRepo {
+    owner: string;
+    repo: string;
+    /** "owner/repo" as GitHub knows it today. */
+    fullName: string;
+    /** True when the input differed from the canonical name (a rename redirect). */
+    renamed: boolean;
+}
+/**
+ * Resolve a repo to its canonical name (v0.18.0, item 15). GitHub's
+ * repo endpoint follows rename redirects, so dbt-labs/dbt-core comes
+ * back as dbt-labs/dbt. Search-dependent flows (scan, wave starter
+ * counts, friction) 422 or return nothing on the old name, so every
+ * entry point resolves before searching. Failures keep the input
+ * name: a genuinely missing repo fails downstream with its real
+ * error, never with a rename-resolution one.
+ */
+export declare function resolveCanonicalRepo(owner: string, repo: string): Promise<CanonicalRepo>;
 /** POST helper for write operations (automation commands). Read paths use apiGet. */
 export declare function apiPost(path: string, body: unknown): Promise<unknown>;
 export interface IssueURL {
@@ -87,11 +105,31 @@ export interface MentionedPRDeps {
  */
 export declare const HOUSE_RULE_FILES: readonly ["CONTRIBUTING.md", ".github/CONTRIBUTING.md", "docs/CONTRIBUTING.md", "contributing.md", "docs/development/contributing.mdx", "docs/development/contributing.md", "AGENTS.md", ".github/AGENTS.md", "docs/AGENTS.md", "CLAUDE.md", ".github/CLAUDE.md", "docs/CLAUDE.md", "AI_POLICY.md", ".github/AI_POLICY.md", "docs/AI_POLICY.md"];
 export interface HouseRuleDeps {
-    /** Test seam: fetch a repo-root file's raw text, or undefined when absent. */
+    /**
+     * Test seam: fetch a repo-root file's raw text, or undefined when absent.
+     * v0.19.0: a fetchRaw that throws surfaces as a provenance "error" (with
+     * the error as the kind string), never as "absent".
+     */
     fetchRaw?: (file: string) => Promise<string | undefined>;
     /** Test seam: fetch the org's AI_POLICY.md text, or undefined when absent. */
     fetchOrgPolicy?: (owner: string) => Promise<string | undefined>;
 }
+/**
+ * v0.19.0: the detailed outcome of one raw policy-file fetch. The old
+ * fetchRawFile collapsed "no such file" and "the fetch failed" into the
+ * same undefined, so friction could not tell a repo with no policy from
+ * a repo whose policy read broke. "error" carries a short kind string
+ * (e.g. "rate limited", "http 500", "network error").
+ */
+export type RawFileFetchStatus = {
+    status: "read";
+    text: string;
+} | {
+    status: "absent";
+} | {
+    status: "error";
+    error: string;
+};
 /**
  * v0.9.3: org-level AI policy. Binding agent rules sometimes live in the
  * org's `.github` repo rather than the project repo (astral-sh's
@@ -99,17 +137,77 @@ export interface HouseRuleDeps {
  * CONTRIBUTING only links to mastodon/.github's AI_POLICY.md). Probed
  * once per org and cached under its own key so a sweep over N repos from
  * one org costs one fetch, not N.
+ *
+ * v0.19.0: the cache entry now carries the full detailed outcome
+ * (read/absent/error); entries written before v0.19.0 (a bare text or
+ * empty string) are treated as a miss and re-fetched.
  */
+export declare function fetchOrgAiPolicyDetailed(owner: string, deps?: HouseRuleDeps): Promise<{
+    file: string;
+    outcome: RawFileFetchStatus;
+}>;
+/** Org-level AI policy text, or undefined when absent or unreadable. */
 export declare function fetchOrgAiPolicy(owner: string, deps?: HouseRuleDeps): Promise<string | undefined>;
 /**
  * v0.9.3: the full policy source set for gate detection: house-rules
  * files (first hit per filename across root, .github/, docs/) plus the
  * org-level AI_POLICY.md when the org publishes one.
+ *
+ * v0.19.0: fetchPolicySourcesWithProvenance adds the read provenance
+ * friction reports; this plain variant delegates and returns the sources
+ * alone, so its callers do not change.
  */
+export declare function fetchPolicySourcesWithProvenance(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
+    sources: {
+        file: string;
+        text: string;
+    }[];
+    provenance: PolicySourceProvenance[];
+}>;
 export declare function fetchPolicySources(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
     file: string;
     text: string;
 }[]>;
+/**
+ * v0.9.3: fetch one policy file's raw text, honoring the API base
+ * override. In proxy mode (GREENLIGHT_GITHUB_BASE_URL set) the raw host
+ * is unreachable with the surrogate credential, so policy files are read
+ * through the contents API instead; otherwise the raw host is used as
+ * before.
+ *
+ * v0.19.0: fetchRawFileDetailed distinguishes three outcomes: read,
+ * absent (the file genuinely is not there), and error (the fetch
+ * failed). fetchRawFile stays as a thin wrapper that returns the text
+ * only when the fetch read, so its callers do not change.
+ */
+export declare function fetchRawFileDetailed(owner: string, repo: string, file: string, headers: Record<string, string>): Promise<RawFileFetchStatus>;
+/**
+ * Fetch all existing house-rules files for a repo (best-effort, cached),
+ * with per-basename read provenance.
+ *
+ * v0.9.3: stop at the first hit per filename (root, then .github/, then
+ * docs/), so a repo with CONTRIBUTING.md at the root does not pay for
+ * two more 404s, and a repo with it only in docs/ is still found (the
+ * AFFiNE shape the 5k scan caught: root-only probing called it
+ * "no policy" while docs/CONTRIBUTING.md existed).
+ *
+ * v0.19.0: provenance carries ONE entry per basename probed: the path
+ * that was read (status "read"), the first candidate path with status
+ * "absent" when every location missed, or status "error" with the first
+ * error kind when a fetch failed before any hit. An error at one
+ * location does not stop the later locations: the read still wins when
+ * a later location has the file.
+ *
+ * The cache payload is { sources, provenance }; entries written before
+ * v0.19.0 (a bare sources array) count as a miss and are re-fetched.
+ */
+export declare function fetchHouseRulesDetailed(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
+    sources: {
+        file: string;
+        text: string;
+    }[];
+    provenance: PolicySourceProvenance[];
+}>;
 /** Fetch all existing house-rules files for a repo (best-effort, cached). */
 export declare function fetchHouseRules(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
     file: string;
@@ -227,6 +325,23 @@ export declare function extractTimelineCrossRefPRs(events: Record<string, unknow
 }>;
 /** Count open issues labelled good-first-issue or help-wanted. */
 export declare function countStarterIssues(owner: string, repo: string): Promise<number | null>;
+/**
+ * v0.19.0 (item 16): the wider starter label set for the candidate
+ * estimate. Repos that never adopted the classic "good first issue" /
+ * "help wanted" pair often label starter work one of these instead.
+ */
+export declare const STARTER_CANDIDATE_LABELS: readonly ["beginner friendly", "beginner", "easy", "starter", "first-timers-only", "up-for-grabs", "good-first-issue"];
+export interface StarterSearchDeps {
+    /** Test seam: run a search query, return its total_count or null. */
+    searchCount?: (query: string) => Promise<number | null>;
+}
+/**
+ * Fallback starter-candidate estimate, used only when the classic
+ * label count is exactly 0. One search call: open, unassigned issues
+ * under the wider starter label set. An estimate for display, never a
+ * score input; null when the search itself fails.
+ */
+export declare function countStarterCandidates(owner: string, repo: string, deps?: StarterSearchDeps): Promise<number | null>;
 /** Detect a collaborators-only PR creation policy via the community metrics endpoint. */
 export declare function detectRepoPolicy(owner: string, repo: string): Promise<{
     collaboratorsOnly: boolean;
@@ -274,6 +389,20 @@ export interface ScanCandidateList {
     /** True when the label pass came back empty and the fallback list was used. */
     fallbackUsed: boolean;
 }
+/**
+ * Default wall-time bound for `greenlight scan`, in seconds (v0.19.0,
+ * item 17): on mega-backlog repos the per-issue verdict pipeline ran
+ * about 25 minutes, so the scan stops with marked partial results when
+ * the budget runs out instead of running open-ended. Override per run
+ * with --max-time <seconds>.
+ */
+export declare const DEFAULT_SCAN_MAX_TIME_SEC = 600;
+/**
+ * Pure wall-time check for the scan loop (v0.19.0, item 17): true once
+ * the elapsed time since startedAtMs has reached the budget. Call with
+ * Date.now() for the nowMs argument. Exported for unit tests.
+ */
+export declare function scanBudgetExceeded(startedAtMs: number, maxTimeSec: number, nowMs: number): boolean;
 export interface ScanDeps {
     starter?: (owner: string, repo: string, limit: number) => Promise<ScanCandidate[]>;
     recent?: (owner: string, repo: string, cap: number) => Promise<ScanCandidate[]>;

package/dist/github.js

@@ -194,6 +194,30 @@ export async function apiGet(path) {
     }
     return res.json();
 }
+/**
+ * Resolve a repo to its canonical name (v0.18.0, item 15). GitHub's
+ * repo endpoint follows rename redirects, so dbt-labs/dbt-core comes
+ * back as dbt-labs/dbt. Search-dependent flows (scan, wave starter
+ * counts, friction) 422 or return nothing on the old name, so every
+ * entry point resolves before searching. Failures keep the input
+ * name: a genuinely missing repo fails downstream with its real
+ * error, never with a rename-resolution one.
+ */
+export async function resolveCanonicalRepo(owner, repo) {
+    const input = { owner, repo, fullName: `${owner}/${repo}`, renamed: false };
+    try {
+        const data = (await apiGet(`/repos/${owner}/${repo}`));
+        const full = String(data.full_name ?? "");
+        const m = /^([^/]+)\/([^/]+)$/.exec(full);
+        if (m && (m[1] !== owner || m[2] !== repo)) {
+            return { owner: m[1], repo: m[2], fullName: full, renamed: true };
+        }
+        return { owner, repo, fullName: full || input.fullName, renamed: false };
+    }
+    catch {
+        return input;
+    }
+}
 /** POST helper for write operations (automation commands). Read paths use apiGet. */
 export async function apiPost(path, body) {
     const headers = {
@@ -376,6 +400,17 @@ export const HOUSE_RULE_FILES = [
     ".github/AI_POLICY.md",
     "docs/AI_POLICY.md",
 ];
+/** Short kind string for a policy-file fetch failure (never the full stack). */
+function classifyFetchError(err) {
+    if (err instanceof RateLimitError)
+        return "rate limited";
+    if (err instanceof RequestTimeoutError)
+        return "timeout";
+    if (err instanceof Error && err.message) {
+        return err.message.length > 120 ? err.message.slice(0, 120) : err.message;
+    }
+    return "fetch error";
+}
 /**
  * v0.9.3: org-level AI policy. Binding agent rules sometimes live in the
  * org's `.github` repo rather than the project repo (astral-sh's
@@ -383,95 +418,203 @@ export const HOUSE_RULE_FILES = [
  * CONTRIBUTING only links to mastodon/.github's AI_POLICY.md). Probed
  * once per org and cached under its own key so a sweep over N repos from
  * one org costs one fetch, not N.
+ *
+ * v0.19.0: the cache entry now carries the full detailed outcome
+ * (read/absent/error); entries written before v0.19.0 (a bare text or
+ * empty string) are treated as a miss and re-fetched.
  */
-export async function fetchOrgAiPolicy(owner, deps = {}) {
+export async function fetchOrgAiPolicyDetailed(owner, deps = {}) {
+    const file = `AI_POLICY.md (org ${owner})`;
     if (!deps.fetchOrgPolicy) {
         const cached = cacheGet("org-ai-policy", [owner.toLowerCase()]);
-        if (cached !== undefined)
-            return cached || undefined;
+        if (cached !== undefined && typeof cached === "object")
+            return { file, outcome: cached };
     }
     const headers = { "User-Agent": "greenlight-cli" };
     const token = githubToken();
     if (token)
         headers["Authorization"] = `Bearer ${token}`;
-    const fetchOrgPolicy = deps.fetchOrgPolicy ??
-        ((o) => fetchRawFile(o, ".github", "AI_POLICY.md", headers));
-    const text = await fetchOrgPolicy(owner);
+    let outcome;
+    if (deps.fetchOrgPolicy) {
+        try {
+            const text = await deps.fetchOrgPolicy(owner);
+            outcome = text ? { status: "read", text } : { status: "absent" };
+        }
+        catch (err) {
+            outcome =
+                err instanceof ApiNotFoundError
+                    ? { status: "absent" }
+                    : { status: "error", error: classifyFetchError(err) };
+        }
+    }
+    else {
+        outcome = await fetchRawFileDetailed(owner, ".github", "AI_POLICY.md", headers);
+    }
     if (!deps.fetchOrgPolicy)
-        cacheSet("org-ai-policy", [owner.toLowerCase()], text ?? "");
-    return text;
+        cacheSet("org-ai-policy", [owner.toLowerCase()], outcome);
+    return { file, outcome };
+}
+/** Org-level AI policy text, or undefined when absent or unreadable. */
+export async function fetchOrgAiPolicy(owner, deps = {}) {
+    const { outcome } = await fetchOrgAiPolicyDetailed(owner, deps);
+    return outcome.status === "read" ? outcome.text : undefined;
 }
 /**
  * v0.9.3: the full policy source set for gate detection: house-rules
  * files (first hit per filename across root, .github/, docs/) plus the
  * org-level AI_POLICY.md when the org publishes one.
+ *
+ * v0.19.0: fetchPolicySourcesWithProvenance adds the read provenance
+ * friction reports; this plain variant delegates and returns the sources
+ * alone, so its callers do not change.
  */
+export async function fetchPolicySourcesWithProvenance(owner, repo, deps = {}) {
+    const [{ sources, provenance }, { file, outcome }] = await Promise.all([
+        fetchHouseRulesDetailed(owner, repo, deps),
+        fetchOrgAiPolicyDetailed(owner, deps),
+    ]);
+    if (outcome.status === "read")
+        sources.push({ file, text: outcome.text });
+    provenance.push(outcome.status === "read"
+        ? { file, scope: "org", status: "read" }
+        : outcome.status === "error"
+            ? { file, scope: "org", status: "error", error: outcome.error }
+            : { file, scope: "org", status: "absent" });
+    return { sources, provenance };
+}
 export async function fetchPolicySources(owner, repo, deps = {}) {
-    const rules = await fetchHouseRules(owner, repo, deps);
-    const orgPolicy = await fetchOrgAiPolicy(owner, deps);
-    if (orgPolicy)
-        rules.push({ file: `AI_POLICY.md (org ${owner})`, text: orgPolicy });
-    return rules;
+    const { sources } = await fetchPolicySourcesWithProvenance(owner, repo, deps);
+    return sources;
 }
 /**
  * v0.9.3: fetch one policy file's raw text, honoring the API base
  * override. In proxy mode (GREENLIGHT_GITHUB_BASE_URL set) the raw host
  * is unreachable with the surrogate credential, so policy files are read
  * through the contents API instead; otherwise the raw host is used as
- * before. Returns undefined when the file does not exist.
+ * before.
+ *
+ * v0.19.0: fetchRawFileDetailed distinguishes three outcomes: read,
+ * absent (the file genuinely is not there), and error (the fetch
+ * failed). fetchRawFile stays as a thin wrapper that returns the text
+ * only when the fetch read, so its callers do not change.
  */
-async function fetchRawFile(owner, repo, file, headers) {
+export async function fetchRawFileDetailed(owner, repo, file, headers) {
     if (githubApiBase() !== DEFAULT_API) {
         try {
             const data = (await apiGet(`/repos/${owner}/${repo}/contents/${file}`));
             if (typeof data.content === "string" && data.encoding === "base64") {
-                return Buffer.from(data.content, "base64").toString("utf8");
+                return { status: "read", text: Buffer.from(data.content, "base64").toString("utf8") };
             }
+            return { status: "absent" };
+        }
+        catch (err) {
+            if (err instanceof ApiNotFoundError)
+                return { status: "absent" };
+            return { status: "error", error: classifyFetchError(err) };
         }
-        catch { /* absent */ }
-        return undefined;
     }
     try {
-        const res = await fetch(`${RAW}/${owner}/${repo}/HEAD/${file}`, { headers });
+        const res = await activeFetch()(`${RAW}/${owner}/${repo}/HEAD/${file}`, { headers });
         if (res.ok)
-            return await res.text();
+            return { status: "read", text: await res.text() };
+        if (res.status === 404)
+            return { status: "absent" };
+        return { status: "error", error: `http ${res.status}` };
+    }
+    catch (err) {
+        return { status: "error", error: classifyFetchError(err) };
     }
-    catch { /* try next */ }
-    return undefined;
 }
-/** Fetch all existing house-rules files for a repo (best-effort, cached). */
-export async function fetchHouseRules(owner, repo, deps = {}) {
+/** Returns the file's text when the fetch reads it, otherwise undefined. */
+async function fetchRawFile(owner, repo, file, headers) {
+    const outcome = await fetchRawFileDetailed(owner, repo, file, headers);
+    return outcome.status === "read" ? outcome.text : undefined;
+}
+/**
+ * Fetch all existing house-rules files for a repo (best-effort, cached),
+ * with per-basename read provenance.
+ *
+ * v0.9.3: stop at the first hit per filename (root, then .github/, then
+ * docs/), so a repo with CONTRIBUTING.md at the root does not pay for
+ * two more 404s, and a repo with it only in docs/ is still found (the
+ * AFFiNE shape the 5k scan caught: root-only probing called it
+ * "no policy" while docs/CONTRIBUTING.md existed).
+ *
+ * v0.19.0: provenance carries ONE entry per basename probed: the path
+ * that was read (status "read"), the first candidate path with status
+ * "absent" when every location missed, or status "error" with the first
+ * error kind when a fetch failed before any hit. An error at one
+ * location does not stop the later locations: the read still wins when
+ * a later location has the file.
+ *
+ * The cache payload is { sources, provenance }; entries written before
+ * v0.19.0 (a bare sources array) count as a miss and are re-fetched.
+ */
+export async function fetchHouseRulesDetailed(owner, repo, deps = {}) {
     if (!deps.fetchRaw) {
         const cached = cacheGet("house-rules", [owner, repo]);
-        if (cached)
-            return cached;
+        if (cached && !Array.isArray(cached) && Array.isArray(cached.provenance)) {
+            return { sources: cached.sources, provenance: cached.provenance };
+        }
     }
     const headers = { "User-Agent": "greenlight-cli" };
     const token = githubToken();
     if (token)
         headers["Authorization"] = `Bearer ${token}`;
-    const fetchRaw = deps.fetchRaw ??
-        ((file) => fetchRawFile(owner, repo, file, headers));
-    // v0.9.3: stop at the first hit per filename (root, then .github/, then
-    // docs/), so a repo with CONTRIBUTING.md at the root does not pay for
-    // two more 404s, and a repo with it only in docs/ is still found (the
-    // AFFiNE shape the 5k scan caught: root-only probing called it
-    // "no policy" while docs/CONTRIBUTING.md existed).
-    const seenBasenames = new Set();
-    const out = [];
+    const fetchOne = async (file) => {
+        if (deps.fetchRaw) {
+            try {
+                const text = await deps.fetchRaw(file);
+                return text ? { status: "read", text } : { status: "absent" };
+            }
+            catch (err) {
+                if (err instanceof ApiNotFoundError)
+                    return { status: "absent" };
+                return { status: "error", error: classifyFetchError(err) };
+            }
+        }
+        return fetchRawFileDetailed(owner, repo, file, headers);
+    };
+    const sources = [];
+    const provenance = [];
     for (const file of HOUSE_RULE_FILES) {
         const base = file.split("/").pop().toLowerCase();
-        if (seenBasenames.has(base))
+        if (provenance.some((p) => p.file.split("/").pop().toLowerCase() === base && p.scope === "repo")) {
             continue;
-        const text = await fetchRaw(file);
-        if (text) {
-            out.push({ file, text });
-            seenBasenames.add(base);
+        }
+        let readAt;
+        let firstError;
+        for (const candidate of HOUSE_RULE_FILES) {
+            if (candidate.split("/").pop().toLowerCase() !== base)
+                continue;
+            const outcome = await fetchOne(candidate);
+            if (outcome.status === "read") {
+                readAt = { file: candidate, text: outcome.text };
+                break;
+            }
+            if (outcome.status === "error" && !firstError) {
+                firstError = { file: candidate, error: outcome.error };
+            }
+        }
+        if (readAt) {
+            sources.push(readAt);
+            provenance.push({ file: readAt.file, scope: "repo", status: "read" });
+        }
+        else if (firstError) {
+            provenance.push({ file: firstError.file, scope: "repo", status: "error", error: firstError.error });
+        }
+        else {
+            provenance.push({ file, scope: "repo", status: "absent" });
         }
     }
     if (!deps.fetchRaw)
-        cacheSet("house-rules", [owner, repo], out);
-    return out;
+        cacheSet("house-rules", [owner, repo], { sources, provenance });
+    return { sources, provenance };
+}
+/** Fetch all existing house-rules files for a repo (best-effort, cached). */
+export async function fetchHouseRules(owner, repo, deps = {}) {
+    const { sources } = await fetchHouseRulesDetailed(owner, repo, deps);
+    return sources;
 }
 /** Fetch CONTRIBUTING.md raw text; returns undefined when the repo has none. */
 export async function fetchContributing(owner, repo) {
@@ -864,6 +1007,40 @@ export async function countStarterIssues(owner, repo) {
         return null;
     }
 }
+/**
+ * v0.19.0 (item 16): the wider starter label set for the candidate
+ * estimate. Repos that never adopted the classic "good first issue" /
+ * "help wanted" pair often label starter work one of these instead.
+ */
+export const STARTER_CANDIDATE_LABELS = [
+    "beginner friendly",
+    "beginner",
+    "easy",
+    "starter",
+    "first-timers-only",
+    "up-for-grabs",
+    "good-first-issue",
+];
+/**
+ * Fallback starter-candidate estimate, used only when the classic
+ * label count is exactly 0. One search call: open, unassigned issues
+ * under the wider starter label set. An estimate for display, never a
+ * score input; null when the search itself fails.
+ */
+export async function countStarterCandidates(owner, repo, deps = {}) {
+    const labels = STARTER_CANDIDATE_LABELS.map((l) => `"${l}"`).join(",");
+    const query = `repo:${owner}/${repo} type:issue state:open no:assignee label:${labels}`;
+    if (deps.searchCount)
+        return deps.searchCount(query);
+    try {
+        const q = encodeURIComponent(query);
+        const data = (await apiGet(`/search/issues?q=${q}&per_page=1`));
+        return data.total_count ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Detect a collaborators-only PR creation policy via the community metrics endpoint. */
 export async function detectRepoPolicy(owner, repo) {
     // Best-effort: no public API exposes pull_request_creation_policy directly,
@@ -1018,6 +1195,22 @@ export async function listRecentUnassignedIssues(owner, repo, cap = 25) {
     const items = await paginate(`/repos/${owner}/${repo}/issues?state=open&sort=created&direction=desc`, 100, 3);
     return toScanCandidates(items).slice(0, cap);
 }
+/**
+ * Default wall-time bound for `greenlight scan`, in seconds (v0.19.0,
+ * item 17): on mega-backlog repos the per-issue verdict pipeline ran
+ * about 25 minutes, so the scan stops with marked partial results when
+ * the budget runs out instead of running open-ended. Override per run
+ * with --max-time <seconds>.
+ */
+export const DEFAULT_SCAN_MAX_TIME_SEC = 600;
+/**
+ * Pure wall-time check for the scan loop (v0.19.0, item 17): true once
+ * the elapsed time since startedAtMs has reached the budget. Call with
+ * Date.now() for the nowMs argument. Exported for unit tests.
+ */
+export function scanBudgetExceeded(startedAtMs, maxTimeSec, nowMs) {
+    return nowMs - startedAtMs >= maxTimeSec * 1000;
+}
 /**
  * Scan candidates for a repo: the label-tagged starter list first; when it
  * is empty, fall back to recent open unassigned issues (opt out with