@oss-autopilot/core 1.15.0 → 1.15.2

package/dist/core/issue-grading.js

@@ -0,0 +1,146 @@
+/**
+ * Issue success-likelihood grade (#858).
+ *
+ * Predicts the probability that a contribution to a given repo will be
+ * accepted and merged, using signals already collected during vetting.
+ *
+ * The grade is letter-based (A/B/C/F — no D). Each signal is graded
+ * independently; the overall grade is the worst of the three, and is
+ * further degraded one step if any signal is unknown (missing data is
+ * treated as a risk, not ignored). This matches the policy previously
+ * described as prose in agents/issue-scout.md.
+ */
+const SEVERITY = { A: 0, B: 1, C: 2, F: 3 };
+const LETTERS = ['A', 'B', 'C', 'F'];
+function worst(grades) {
+    return grades.reduce((acc, g) => (SEVERITY[g.letter] > SEVERITY[acc.letter] ? g : acc));
+}
+function degradeOneStep(letter) {
+    return LETTERS[Math.min(SEVERITY[letter] + 1, LETTERS.length - 1)];
+}
+/**
+ * Coerce a candidate numeric signal to `number` if it's finite and in
+ * the given range, otherwise `null`. Non-finite, NaN, and out-of-range
+ * values are treated as unknown (and therefore trigger the degrade
+ * rule) rather than silently producing bogus grades from garbage input.
+ */
+function sanitize(value, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return null;
+    if (value < min || value > max)
+        return null;
+    return value;
+}
+function gradeResponsiveness(avgResponseDays) {
+    if (avgResponseDays < 3)
+        return { letter: 'A', detail: `~${Math.round(avgResponseDays)}-day avg response` };
+    if (avgResponseDays < 14)
+        return { letter: 'B', detail: `${Math.round(avgResponseDays)}-day avg response` };
+    if (avgResponseDays <= 60)
+        return { letter: 'C', detail: `${Math.round(avgResponseDays)}-day avg response` };
+    return { letter: 'F', detail: 'unresponsive maintainers' };
+}
+function gradeMergeRate(mergeRate) {
+    const pct = Math.round(mergeRate * 100);
+    if (mergeRate > 0.7)
+        return { letter: 'A', detail: `merges ${pct}% of PRs` };
+    if (mergeRate >= 0.4)
+        return { letter: 'B', detail: `merges ${pct}% of PRs` };
+    if (mergeRate >= 0.1)
+        return { letter: 'C', detail: `merges ${pct}% of PRs` };
+    return { letter: 'F', detail: `merges ${pct}% of PRs` };
+}
+function gradeActivity(daysSinceLastCommit) {
+    if (daysSinceLastCommit < 7)
+        return { letter: 'A', detail: 'commits in last week' };
+    if (daysSinceLastCommit < 30)
+        return { letter: 'B', detail: 'commits in last month' };
+    if (daysSinceLastCommit < 90)
+        return { letter: 'C', detail: 'commits in last 90 days' };
+    return { letter: 'F', detail: `no commits in ${daysSinceLastCommit}+ days` };
+}
+/**
+ * Build `GradeSignals` from a vet candidate's project health plus the
+ * optional autopilot-tracked repo score.
+ *
+ * Notes on each signal:
+ *
+ * - `avgResponseDays` — `@oss-scout/core`'s `projectHealth.avgIssueResponseDays`
+ *   is a hardcoded `0` placeholder (it doesn't yet make the additional API
+ *   calls needed to compute a real value). We therefore prefer
+ *   `repoScore.avgResponseDays`, which autopilot derives from its own PR
+ *   tracking, and fall back to `null` (unknown) if neither source has a
+ *   usable value.
+ * - `mergeRate` — derived from repoScore counts. Requires a non-empty PR
+ *   history; `0/0` is `null`, not `0`.
+ * - `daysSinceLastCommit` — taken from scout's `projectHealth`, but only
+ *   when scout's health check succeeded (`checkFailed` means scout filled
+ *   in sentinels and shouldn't be trusted).
+ */
+export function deriveGradeSignals(params) {
+    const { projectHealth, repoScore } = params;
+    const healthTrusted = !projectHealth.checkFailed;
+    const avgResponseDays = sanitize(repoScore?.avgResponseDays, 0, Number.MAX_SAFE_INTEGER) ??
+        (healthTrusted ? sanitize(projectHealth.avgIssueResponseDays, 0.001, Number.MAX_SAFE_INTEGER) : null);
+    const daysSinceLastCommit = healthTrusted
+        ? sanitize(projectHealth.daysSinceLastCommit, 0, Number.MAX_SAFE_INTEGER)
+        : null;
+    let mergeRate = null;
+    if (repoScore) {
+        const merged = sanitize(repoScore.mergedPRCount, 0, Number.MAX_SAFE_INTEGER);
+        const closed = sanitize(repoScore.closedWithoutMergeCount, 0, Number.MAX_SAFE_INTEGER);
+        if (merged !== null && closed !== null) {
+            const total = merged + closed;
+            mergeRate = total === 0 ? null : merged / total;
+        }
+    }
+    return { avgResponseDays, mergeRate, daysSinceLastCommit };
+}
+/**
+ * End-to-end helper for vet callers: reads the repo score, derives
+ * signals from a scout candidate, and returns the grade. Callers pass
+ * the `projectHealth` straight through from `scout.vetIssue()`.
+ */
+export function gradeFromCandidate(params) {
+    const repoScore = params.getRepoScore(params.repo);
+    return computeSuccessGrade(deriveGradeSignals({
+        projectHealth: params.projectHealth,
+        repoScore: repoScore
+            ? {
+                mergedPRCount: repoScore.mergedPRCount,
+                closedWithoutMergeCount: repoScore.closedWithoutMergeCount,
+                avgResponseDays: repoScore.avgResponseDays,
+            }
+            : null,
+    }));
+}
+export function computeSuccessGrade(signals) {
+    const graded = [];
+    const unknowns = [];
+    const resp = sanitize(signals.avgResponseDays, 0, Number.MAX_SAFE_INTEGER);
+    if (resp === null)
+        unknowns.push('maintainer responsiveness');
+    else
+        graded.push(gradeResponsiveness(resp));
+    const mr = sanitize(signals.mergeRate, 0, 1);
+    if (mr === null)
+        unknowns.push('merge rate');
+    else
+        graded.push(gradeMergeRate(mr));
+    const act = sanitize(signals.daysSinceLastCommit, 0, Number.MAX_SAFE_INTEGER);
+    if (act === null)
+        unknowns.push('activity');
+    else
+        graded.push(gradeActivity(act));
+    // No signal available at all — give F so callers see missing data as a
+    // strong negative rather than a neutral grade.
+    if (graded.length === 0) {
+        return { letter: 'F', reason: `unknown ${unknowns.join(', ')}` };
+    }
+    const worstKnown = worst(graded);
+    const finalLetter = unknowns.length > 0 ? degradeOneStep(worstKnown.letter) : worstKnown.letter;
+    const reasonParts = [worstKnown.detail];
+    if (unknowns.length > 0)
+        reasonParts.push(`unknown ${unknowns.join(', ')}`);
+    return { letter: finalLetter, reason: reasonParts.join(', ') };
+}

package/dist/core/linked-pr-classification.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Linked-PR classification (#910, #978).
+ *
+ * Given the first linked PR on an issue, decide how it affects whether
+ * the issue is actionable for the current user. Previously described as
+ * prose in agents/issue-scout.md; extracted here as a pure function so
+ * the classification is unit-testable and uniform across callers.
+ *
+ * Integration with the vet flow is deferred — scout does not yet surface
+ * linked-PR metadata on `IssueCandidate`, so consumers need to fetch the
+ * linked PR themselves (e.g. via Octokit) and hand the shape to this
+ * function. See #978 for the upstream data-contract work.
+ */
+export type LinkedPRClassification = 'none' | 'user_open' | 'user_closed' | 'user_merged' | 'other_open' | 'other_closed' | 'other_merged';
+export type LinkedPRState = 'open' | 'closed' | 'merged';
+export interface LinkedPR {
+    /**
+     * May be `null` for deleted GitHub accounts ("ghost" users); the
+     * declared type on GitHub's API allows null here even though the REST
+     * schema example typically shows a populated user.
+     */
+    author: {
+        login: string;
+    } | null;
+    state: LinkedPRState;
+}
+export declare function classifyLinkedPR(params: {
+    linkedPR: LinkedPR | null;
+    userLogin: string;
+}): LinkedPRClassification;

package/dist/core/linked-pr-classification.js

@@ -0,0 +1,53 @@
+/**
+ * Linked-PR classification (#910, #978).
+ *
+ * Given the first linked PR on an issue, decide how it affects whether
+ * the issue is actionable for the current user. Previously described as
+ * prose in agents/issue-scout.md; extracted here as a pure function so
+ * the classification is unit-testable and uniform across callers.
+ *
+ * Integration with the vet flow is deferred — scout does not yet surface
+ * linked-PR metadata on `IssueCandidate`, so consumers need to fetch the
+ * linked PR themselves (e.g. via Octokit) and hand the shape to this
+ * function. See #978 for the upstream data-contract work.
+ */
+/**
+ * Normalize a state value from either REST (lowercase `open`/`closed`
+ * plus a separate `merged` boolean) or GraphQL (uppercase `OPEN`/
+ * `CLOSED`/`MERGED` union) into our internal lowercase form. Callers
+ * converting from REST should pre-mix `merged` into the state before
+ * calling; see the tests for expected shapes.
+ */
+function normalizeState(state) {
+    const lower = state.toLowerCase();
+    if (lower === 'open' || lower === 'closed' || lower === 'merged')
+        return lower;
+    return null;
+}
+export function classifyLinkedPR(params) {
+    const { linkedPR, userLogin } = params;
+    if (!linkedPR)
+        return 'none';
+    const state = normalizeState(linkedPR.state);
+    // Unknown state (e.g., future-extended values) is safest to treat as
+    // "closed" — skip-worthy but non-fatal — rather than throwing and
+    // breaking the whole vetting pipeline on one malformed payload.
+    const effectiveState = state ?? 'closed';
+    // GitHub usernames are case-insensitive ASCII. Ghost authors (deleted
+    // accounts) return `null` or an empty login; in both cases we can't
+    // prove the PR is the user's own, so we classify it as "other_*".
+    const authorLogin = linkedPR.author?.login ?? '';
+    const isUserOwn = authorLogin !== '' && userLogin !== '' && authorLogin.toLowerCase() === userLogin.toLowerCase();
+    if (isUserOwn) {
+        if (effectiveState === 'open')
+            return 'user_open';
+        if (effectiveState === 'merged')
+            return 'user_merged';
+        return 'user_closed';
+    }
+    if (effectiveState === 'open')
+        return 'other_open';
+    if (effectiveState === 'merged')
+        return 'other_merged';
+    return 'other_closed';
+}

package/dist/formatters/json.d.ts

@@ -313,6 +313,11 @@ export interface VetOutput {
     reasonsToSkip: string[];
     projectHealth: unknown;
     vettingResult: unknown;
+    /** Success-likelihood grade (#858): predicts whether a PR will merge. */
+    grade: {
+        letter: 'A' | 'B' | 'C' | 'F';
+        reason: string;
+    };
 }
 /** Output of the comments command */
 export interface CommentsOutput {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {