@loopover/engine 1.0.0

package/dist/reward-risk.d.ts

@@ -0,0 +1,223 @@
+import type { ScorePreviewResult } from "./scoring/preview.js";
+import type { CheckSummaryRecord, CollisionReport, ContributorFit, ContributorOutcomeHistory, ContributorProfile, ContributorScoringProfile, IssueRecord, LaneAdvice, PullRequestFileRecord, PullRequestRecord, PullRequestReviewRecord, QueueHealth, RecentMergedPullRequestRecord, RepoFitRecommendation, RepositoryRecord, RoleContext, ScoringModelSnapshotRecord } from "./types/reward-risk-types.js";
+/**
+ * Minimal covariant view of `buildPullRequestReviewIntelligence`'s return — only the fields this module
+ * reads. The full `src` type (`PullRequestMaintainerPacket & …`) is covariantly assignable to it.
+ */
+export type PullRequestReviewIntelligenceView = {
+    roleContext: {
+        maintainerLane: boolean;
+    };
+    outcomeContext?: {
+        closedPullRequestRate: number;
+    } | undefined;
+    reviewSignals: {
+        linkedIssues: readonly unknown[];
+        collisionClusters: number;
+        approvalCount: number;
+    };
+    changeSummary: {
+        fileCount: number;
+        additions: number;
+        deletions: number;
+        codeFileCount: number;
+        testFileCount: number;
+    };
+};
+/** Input shared by {@link buildPullRequestReviewability} and the injected `buildPullRequestReviewIntelligence`. */
+export type PullRequestReviewabilityInput = {
+    repo: RepositoryRecord | null;
+    pullRequest: PullRequestRecord | null;
+    issues: IssueRecord[];
+    pullRequests: PullRequestRecord[];
+    files: PullRequestFileRecord[];
+    reviews: PullRequestReviewRecord[];
+    checks: CheckSummaryRecord[];
+    recentMergedPullRequests: RecentMergedPullRequestRecord[];
+    repoFullName: string;
+    pullNumber: number;
+    profile?: ContributorProfile | null | undefined;
+    outcomeHistory?: ContributorOutcomeHistory | null | undefined;
+};
+/**
+ * The `src/signals/engine.ts` builders reward-risk depends on, injected so this package stays free of any
+ * `src/` import. The real `src`-typed builders bind cleanly: their argument records are wider than (assignable
+ * from) these engine mirrors, and their richer return types are covariantly assignable to the narrowed views
+ * above. `isFailingCheckSummary` is imported directly from `./signals/check-summary.js` (#4256).
+ */
+export type RewardRiskEngineDeps = {
+    buildRoleContext: (args: {
+        login: string;
+        repo: RepositoryRecord | null;
+        repoFullName: string;
+        pullRequests: PullRequestRecord[];
+        issues: IssueRecord[];
+        profile: ContributorProfile;
+    }) => RoleContext;
+    buildLaneAdvice: (repo: RepositoryRecord | null, fullName: string) => LaneAdvice;
+    buildCollisionReport: (fullName: string, issues: IssueRecord[], pullRequests: PullRequestRecord[], recentMergedPullRequests: RecentMergedPullRequestRecord[]) => CollisionReport;
+    buildQueueHealth: (repo: RepositoryRecord | null, issues: IssueRecord[], pullRequests: PullRequestRecord[], collisions: CollisionReport) => QueueHealth;
+    buildRepoFitRecommendation: (args: {
+        login: string;
+        repo: RepositoryRecord | null;
+        repoFullName: string;
+        profile: ContributorProfile;
+        outcomeHistory: ContributorOutcomeHistory;
+        issues: IssueRecord[];
+        pullRequests: PullRequestRecord[];
+    }) => RepoFitRecommendation;
+    buildContributorIntakeHealth: (repo: RepositoryRecord | null, issues: IssueRecord[], pullRequests: PullRequestRecord[], fullName: string, collisions: CollisionReport) => {
+        level: "healthy" | "watch" | "strained" | "blocked";
+    };
+    buildPullRequestReviewIntelligence: (args: PullRequestReviewabilityInput) => PullRequestReviewIntelligenceView;
+};
+export type RewardRiskActionKind = "cleanup_existing_prs" | "land_existing_prs" | "close_or_withdraw_low_fit_prs" | "open_new_direct_pr" | "file_issue_discovery" | "maintainer_lane_improve_repo" | "maintainer_cut_readiness";
+/** Severity tier for a reward/risk action, from most to least urgent. */
+export type RewardRiskActionSeverity = "critical" | "warning" | "tip" | "info";
+export type RewardRiskAction = {
+    actionKind: RewardRiskActionKind;
+    repoFullName: string;
+    /** Severity tier: critical = eligibility blocker; warning = active penalty; tip = multiplier opportunity; info = planning context. */
+    severity: RewardRiskActionSeverity;
+    priorityScore: number;
+    laneValueScore: number;
+    scoreabilityScore: number;
+    personalFitScore: number;
+    riskPenalty: number;
+    maintainerFrictionPenalty: number;
+    actionLeverageScore: number;
+    whyThisHelps: string[];
+    nextActions: string[];
+};
+export type RepoRewardRisk = {
+    login: string;
+    repoFullName: string;
+    generatedAt: string;
+    roleContext: RoleContext;
+    lane: LaneAdvice;
+    recommendation: RepoFitRecommendation["recommendation"];
+    rewardUpside: {
+        relevantLane: "direct_pr" | "issue_discovery" | "maintainer_lane" | "none";
+        repoSlice: number;
+        directPrSlice: number;
+        issueDiscoverySlice: number;
+        maintainerCutSlice: number;
+        labelMultiplier: number;
+        issueMultiplier: number;
+        estimatedScoreIfClean: number;
+        currentEstimatedScore: number;
+        /** Explicit opportunity factors: competition and freshness of available work. */
+        opportunityFactors: {
+            /** 0–1; higher = more competing open PRs with duplicate/collision risk. */
+            competitionFactor: number;
+            /** 0–1; higher = issues in this repo were created or updated more recently. */
+            freshnessFactor: number;
+        };
+    };
+    scoreBlockers: string[];
+    riskBreakdown: {
+        queueBurden: QueueHealth["level"];
+        queueBurdenScore: number;
+        duplicateClusters: number;
+        highRiskDuplicateClusters: number;
+        closedPullRequestRate: number;
+        openPullRequests: number;
+        credibility: number;
+        reviewChurnRisk: "low" | "medium" | "high";
+    };
+    actionImpact: {
+        currentOpenPrCount: number;
+        openPrThreshold: number;
+        openPrMultiplierDelta: string;
+        estimatedScoreDelta: string;
+        cleanupNeeded: number;
+        explanation: string;
+    };
+    currentPreview: ScorePreviewResult;
+    afterCleanupPreview: ScorePreviewResult;
+    actions: RewardRiskAction[];
+    whyThisHelps: string[];
+    nextActions: string[];
+    summary: string;
+};
+/** A registered repo where a small number of PR cleanups would unlock or improve scoring. */
+export type EligibilityGapEntry = {
+    repoFullName: string;
+    /** Number of open PRs to land or withdraw before the open-PR gate improves. */
+    prsToUnlock: number;
+    /** Estimated merged score after reaching the threshold (from afterCleanupPreview). */
+    estimatedScoreAtThreshold: number;
+    recommendation: string;
+};
+export type ContributorRewardRiskStrategy = {
+    login: string;
+    generatedAt: string;
+    scoringModelSnapshotId: string;
+    summary: string;
+    topActions: RewardRiskAction[];
+    repoAnalyses: RepoRewardRisk[];
+    reasoning: string[];
+    actionImpact: string[];
+    nextActions: string[];
+    /** Repos where 1–5 PR cleanups would flip the open-PR gate toward scoreable. Sorted by fewest prsToUnlock. */
+    eligibilityGap: EligibilityGapEntry[];
+};
+export type MaintainerNoiseReport = {
+    repoFullName: string;
+    generatedAt: string;
+    score: number;
+    level: "low" | "medium" | "high" | "critical";
+    noiseSources: string[];
+    maintainerActions: Array<"review_now" | "needs_author" | "likely_duplicate" | "close_or_redirect" | "watch" | "maintainer_lane">;
+    queueHealth: QueueHealth;
+    summary: string;
+};
+export type PullRequestReviewability = {
+    repoFullName: string;
+    pullNumber: number;
+    generatedAt: string;
+    score: number;
+    action: "review_now" | "needs_author" | "likely_duplicate" | "close_or_redirect" | "watch" | "maintainer_lane";
+    noiseSources: string[];
+    whyThisHelps: string[];
+    maintainerNextSteps: string[];
+    privateSummary: string;
+};
+export declare function buildRepoRewardRisk(args: {
+    login: string;
+    repo: RepositoryRecord | null;
+    repoFullName: string;
+    profile: ContributorProfile;
+    outcomeHistory: ContributorOutcomeHistory;
+    scoringSnapshot: ScoringModelSnapshotRecord;
+    scoringProfile?: ContributorScoringProfile | null | undefined;
+    issues: IssueRecord[];
+    pullRequests: PullRequestRecord[];
+    recentMergedPullRequests?: RecentMergedPullRequestRecord[] | undefined;
+    /** Repo primary language (from sync metadata / ContributorFit.languageFit),
+     *  used for the personalFit language-match bonus. */
+    repoLanguage?: string | null | undefined;
+}, deps: RewardRiskEngineDeps): RepoRewardRisk;
+export declare function buildContributorRewardRiskStrategy(args: {
+    login: string;
+    fit: ContributorFit;
+    scoringProfile: ContributorScoringProfile;
+    scoringSnapshot: ScoringModelSnapshotRecord;
+    outcomeHistory: ContributorOutcomeHistory;
+    repositories: RepositoryRecord[];
+    allIssues: IssueRecord[];
+    allPullRequests: PullRequestRecord[];
+    recentMergedPullRequests?: RecentMergedPullRequestRecord[] | undefined;
+}, deps: RewardRiskEngineDeps): ContributorRewardRiskStrategy;
+export declare function buildMaintainerNoiseReport(repo: RepositoryRecord | null, issues: IssueRecord[], pullRequests: PullRequestRecord[], recentMergedPullRequests: RecentMergedPullRequestRecord[], fullName: string, deps: RewardRiskEngineDeps): MaintainerNoiseReport;
+export declare function buildPullRequestReviewability(args: PullRequestReviewabilityInput, deps: RewardRiskEngineDeps): PullRequestReviewability;
+declare function bestFitLabels(repo: RepositoryRecord | null): string[];
+declare function pickIssueTimestamp(issue: IssueRecord): string | null;
+/** Unknown/unparseable timestamps floor freshness (parity with gittensory-engine opportunity-freshness.ts). */
+declare function issueAgeDays(value: string | null): number;
+export declare const rewardRiskFreshnessInternals: {
+    pickIssueTimestamp: typeof pickIssueTimestamp;
+    issueAgeDays: typeof issueAgeDays;
+    bestFitLabels: typeof bestFitLabels;
+};
+export {};