@reneturcios/greenlight 0.3.9 → 0.3.11

package/dist/digest.d.ts

@@ -0,0 +1,212 @@
+import { type GuardClaim } from "./guard.js";
+import type { CommentSignal, LinkedPR } from "./types.js";
+export declare const DIGEST_VERSION = "0.3.11";
+/** Default cap for list fetches; --limit overrides. The true total is always reported. */
+export declare const DEFAULT_DIGEST_LIMIT = 50;
+/** A claim on an open issue with no open PR after this many days is stale. */
+export declare const STALE_CLAIM_DAYS = 14;
+/** At this age the suggested action flips from "nudge" to "release". */
+export declare const RELEASE_CLAIM_DAYS = 30;
+export interface DigestPR {
+    number: number;
+    title: string;
+    body: string;
+    author: string;
+    headRef: string;
+    createdAt: string;
+    url: string;
+}
+/** An issue this digest cares about, with its repo (cross-repo links supported). */
+export interface DigestIssueKey {
+    owner: string;
+    repo: string;
+    number: number;
+    /** "#4668" for same-repo, "acme/widgets#123" for cross-repo. */
+    label: string;
+}
+export interface DigestRace {
+    issue: DigestIssueKey;
+    issueTitle: string;
+    issueUrl: string;
+    prs: DigestPR[];
+    /** The earliest claim on the issue, if any. */
+    earliestClaim: {
+        author: string;
+        createdAt: string;
+        strength: string;
+        phrase: string;
+    } | null;
+    /** "first claim: @x on DATE; first PR opened: #N by @y on DATE; the other PR(s) duplicate effort". */
+    arbitration: string;
+}
+export interface DigestClaimConflict {
+    pr: DigestPR;
+    issue: DigestIssueKey;
+    issueTitle: string;
+    issueUrl: string;
+    foreignClaims: GuardClaim[];
+}
+export interface DigestStaleClaim {
+    issue: DigestIssueKey;
+    issueTitle: string;
+    issueUrl: string;
+    claimant: string;
+    claimDate: string;
+    ageDays: number;
+    /** "nudge @x" under 30 days, "release the claim" at 30+. */
+    action: string;
+}
+export interface DigestAssignmentConflict {
+    pr: DigestPR;
+    issue: DigestIssueKey;
+    issueTitle: string;
+    issueUrl: string;
+    /** Current assignees, or [] when the issue is assigned to nobody. */
+    assignees: string[];
+}
+export interface DigestSectionNote {
+    section: string;
+    note: string;
+}
+export interface DigestResult {
+    repo: string;
+    races: DigestRace[];
+    claimConflicts: DigestClaimConflict[];
+    staleClaims: DigestStaleClaim[];
+    assignmentConflicts: DigestAssignmentConflict[];
+    /** Sections that could not be computed, with the reason why. */
+    degraded: DigestSectionNote[];
+    /** "# of sections zero" friendly summary header. */
+    summary: string;
+    prCap: number;
+    trueOpenPRs: number | null;
+    issueCap: number;
+    trueOpenIssues: number | null;
+    /** True when at least one race exists (--fail-on-race maps this to exit code 3). */
+    hasRaces: boolean;
+    markdown: string;
+}
+export interface DigestIssueMeta {
+    number: number;
+    title: string;
+    state: string;
+    author: string;
+    url: string;
+    commentsCount: number;
+    assignees: string[];
+    /** Full comments, fetched only when the candidate needs claims (see budget notes). */
+    comments?: CommentSignal[];
+}
+/**
+ * Issue keys a PR links to: same-repo closing links plus cross-repo
+ * closing references (guard's extractors, reused exactly).
+ */
+export declare function extractPRIssueKeys(pull: DigestPR, prOwner: string, prRepo: string): DigestIssueKey[];
+/** Group open PRs by issue key; groups of 2+ are races. */
+export declare function groupPRsByIssue(prs: DigestPR[], prOwner: string, prRepo: string): Map<string, {
+    key: DigestIssueKey;
+    prs: DigestPR[];
+}>;
+/**
+ * One race: earliest claim (author + date) and earliest PR opened, with a
+ * one-line arbitration summary. Pure: issue comments and PR groups are
+ * injected.
+ */
+export declare function buildRace(group: {
+    key: DigestIssueKey;
+    prs: DigestPR[];
+}, issueTitle: string, issueUrl: string, comments: CommentSignal[], now?: Date): DigestRace;
+/**
+ * Claimed-by-other conflicts: open PRs whose linked issue carries a claim
+ * by someone other than the PR author that predates the PR. Pure: per-issue
+ * comments and author are injected; splitIssueClaims (guard) does the
+ * actual matching.
+ */
+export declare function buildClaimConflicts(args: {
+    prs: DigestPR[];
+    prOwner: string;
+    prRepo: string;
+    issueData: Map<string, {
+        key: DigestIssueKey;
+        title: string;
+        url: string;
+        author: string;
+        comments: CommentSignal[];
+    }>;
+}): DigestClaimConflict[];
+/**
+ * Stale claims: open issues with a claim older than STALE_CLAIM_DAYS and
+ * NO open PR linked in the issue's timeline. Pure: claims come from
+ * injected comments; the timeline result is injected as LinkedPR[].
+ */
+export declare function buildStaleClaims(candidates: Array<{
+    key: DigestIssueKey;
+    title: string;
+    url: string;
+    comments: CommentSignal[];
+    linkedPRs: LinkedPR[];
+}>, now?: Date): DigestStaleClaim[];
+/**
+ * Assignment-gate conflicts: only runs when the repo's gates say
+ * assignment is required. A PR whose author is not among the issue's
+ * assignees is flagged; "assigned to nobody" is its own flavor.
+ */
+export declare function buildAssignmentConflicts(args: {
+    prs: DigestPR[];
+    prOwner: string;
+    prRepo: string;
+    assignmentRequired: boolean;
+    assigneesByIssue: Map<string, {
+        key: DigestIssueKey;
+        title: string;
+        url: string;
+        assignees: string[];
+    }>;
+}): DigestAssignmentConflict[];
+export declare function buildDigestSummary(args: {
+    repo: string;
+    races: number;
+    claimConflicts: number;
+    staleClaims: number;
+    assignmentConflicts: number;
+    prCap: number;
+    trueOpenPRs: number | null;
+}): string;
+export declare function renderDigestMarkdown(result: DigestResult): string;
+interface IssueListItem {
+    number?: unknown;
+    title?: unknown;
+    user?: {
+        login?: unknown;
+    };
+    state?: unknown;
+    comments?: unknown;
+    html_url?: unknown;
+    assignees?: Array<{
+        login?: unknown;
+    }>;
+    pull_request?: unknown;
+}
+export interface DigestDeps {
+    listOpenPRs?: (owner: string, repo: string, limit: number) => Promise<{
+        prs: DigestPR[];
+        total: number | null;
+    }>;
+    listOpenIssues?: (owner: string, repo: string, limit: number) => Promise<{
+        issues: IssueListItem[];
+        total: number | null;
+    }>;
+    fetchIssueMeta?: (owner: string, repo: string, number: number) => Promise<DigestIssueMeta>;
+    fetchIssueComments?: (owner: string, repo: string, number: number) => Promise<CommentSignal[]>;
+    fetchLinkedPRs?: (owner: string, repo: string, issueNumber: number) => Promise<LinkedPR[]>;
+    fetchContributing?: (owner: string, repo: string) => Promise<string | undefined>;
+}
+/**
+ * Full digest for owner/repo. Best-effort throughout: a section whose
+ * data cannot be read is recorded in `degraded` with the reason, never
+ * presented as a clean zero.
+ */
+export declare function digestRepo(owner: string, repo: string, limit: number, deps?: DigestDeps, opts?: {
+    now?: Date;
+}): Promise<DigestResult>;
+export {};