@oss-autopilot/core 0.53.1 → 0.55.0

package/dist/core/status-determination.js

@@ -5,6 +5,8 @@
  * granular action/wait reasons, and staleness tier for a single PR based on
  * its CI, review, merge-conflict, and timeline signals.
  */
+/** Days of inactivity after which an actionable CI failure is demoted to stale_ci_failure (#675). */
+export const STALE_CI_DEMOTION_DAYS = 5;
 /**
  * CI-fix bots that push commits as a direct result of the contributor's push (#568).
  * Their commits represent contributor work and should count as addressing feedback.
@@ -43,35 +45,89 @@ export function isCommitAfterComment(commitDate, commentDate) {
     }
     return commitMs - commentMs >= MIN_RESPONSE_GAP_MS;
 }
+/**
+ * Resolve the latest commit date, filtering out non-contributor commits (#547, #568).
+ * Returns undefined when the commit was by a non-contributor or when no date is available.
+ */
+function resolveContributorCommitDate(input) {
+    const { latestCommitDate, latestCommitAuthor, contributorUsername } = input;
+    if (!latestCommitDate)
+        return undefined;
+    return isContributorCommit(latestCommitAuthor, contributorUsername) ? latestCommitDate : undefined;
+}
+/** Check whether an unresponded comment has been addressed by a subsequent contributor commit. */
+function isCommentAddressedByCommit(commitDate, commentDate, changesRequestedDate) {
+    if (!commitDate || !commentDate)
+        return false;
+    if (!isCommitAfterComment(commitDate, commentDate))
+        return false;
+    // Safety net (#431): if a CHANGES_REQUESTED review came after the commit, it's not addressed
+    if (changesRequestedDate && commitDate < changesRequestedDate)
+        return false;
+    return true;
+}
+/** Check whether a changes_requested review has been addressed by a subsequent contributor commit. */
+function isChangesAddressedByCommit(commitDate, changesRequestedDate) {
+    if (!commitDate || !changesRequestedDate)
+        return false;
+    return commitDate >= changesRequestedDate;
+}
+/**
+ * Collect all applicable action reasons independently, without short-circuiting (#675).
+ * Used alongside the priority-based decision tree to surface secondary issues.
+ */
+function collectAllActionReasons(input) {
+    const { ciStatus, hasMergeConflict, hasUnrespondedComment, hasIncompleteChecklist, reviewDecision, lastMaintainerCommentDate, latestChangesRequestedDate, hasActionableCIFailure = true, } = input;
+    const commitDate = resolveContributorCommitDate(input);
+    const reasons = [];
+    if (hasUnrespondedComment &&
+        !isCommentAddressedByCommit(commitDate, lastMaintainerCommentDate, latestChangesRequestedDate)) {
+        reasons.push('needs_response');
+    }
+    if (reviewDecision === 'changes_requested' &&
+        latestChangesRequestedDate &&
+        !isChangesAddressedByCommit(commitDate, latestChangesRequestedDate)) {
+        reasons.push('needs_changes');
+    }
+    if (ciStatus === 'failing' && hasActionableCIFailure) {
+        reasons.push('failing_ci');
+    }
+    if (hasMergeConflict) {
+        reasons.push('merge_conflict');
+    }
+    if (hasIncompleteChecklist) {
+        reasons.push('incomplete_checklist');
+    }
+    return reasons.length > 0 ? reasons : undefined;
+}
 /**
  * Determine the overall status of a PR based on its signals.
  */
 export function determineStatus(input) {
-    const { ciStatus, hasMergeConflict, hasUnrespondedComment, hasIncompleteChecklist, reviewDecision, daysSinceActivity, dormantThreshold, approachingThreshold, latestCommitDate: rawCommitDate, latestCommitAuthor, contributorUsername, lastMaintainerCommentDate, latestChangesRequestedDate, hasActionableCIFailure = true, } = input;
+    const primary = determinePrimaryStatus(input);
+    const actionReasons = collectAllActionReasons(input);
+    if (actionReasons) {
+        return { ...primary, actionReasons };
+    }
+    return primary;
+}
+/**
+ * Priority-based decision tree for the primary status classification.
+ * Returns the single highest-priority status; `determineStatus` augments
+ * this with the full `actionReasons` array.
+ */
+function determinePrimaryStatus(input) {
+    const { ciStatus, hasMergeConflict, hasUnrespondedComment, hasIncompleteChecklist, reviewDecision, daysSinceActivity, dormantThreshold, approachingThreshold, lastMaintainerCommentDate, latestChangesRequestedDate, hasActionableCIFailure = true, } = input;
     // Compute staleness tier (independent of status)
     let stalenessTier = 'active';
     if (daysSinceActivity >= dormantThreshold)
         stalenessTier = 'dormant';
     else if (daysSinceActivity >= approachingThreshold)
         stalenessTier = 'approaching_dormant';
-    // Only count the latest commit if it was authored by the contributor or a
-    // CI bot (#547, #568). Non-contributor commits (maintainer merge commits,
-    // GitHub suggestion commits) should not mask unaddressed feedback.
-    const latestCommitDate = rawCommitDate && isContributorCommit(latestCommitAuthor, contributorUsername) ? rawCommitDate : undefined;
+    const commitDate = resolveContributorCommitDate(input);
     // Priority order: needs_addressing (response/changes/ci/conflict/checklist) > waiting_on_maintainer (review/merge/addressed/ci_blocked)
     if (hasUnrespondedComment) {
-        // If the contributor pushed a commit after the maintainer's comment,
-        // the changes have been addressed — waiting for maintainer re-review.
-        // Require a minimum 2-minute gap to avoid false positives from race
-        // conditions (pushing while review is being submitted) (#547).
-        if (latestCommitDate &&
-            lastMaintainerCommentDate &&
-            isCommitAfterComment(latestCommitDate, lastMaintainerCommentDate)) {
-            // Safety net (#431): if a CHANGES_REQUESTED review was submitted after
-            // the commit, the maintainer still expects changes — don't mask it
-            if (latestChangesRequestedDate && latestCommitDate < latestChangesRequestedDate) {
-                return { status: 'needs_addressing', actionReason: 'needs_response', stalenessTier };
-            }
+        if (isCommentAddressedByCommit(commitDate, lastMaintainerCommentDate, latestChangesRequestedDate)) {
             if (ciStatus === 'failing' && hasActionableCIFailure)
                 return { status: 'needs_addressing', actionReason: 'failing_ci', stalenessTier };
             // Non-actionable CI failures (infrastructure, fork, auth) don't block changes_addressed —
@@ -81,9 +137,8 @@ export function determineStatus(input) {
         return { status: 'needs_addressing', actionReason: 'needs_response', stalenessTier };
     }
     // Review requested changes but no unresponded comment.
-    // If the latest commit is before the review, the contributor hasn't addressed it yet.
     if (reviewDecision === 'changes_requested' && latestChangesRequestedDate) {
-        if (!latestCommitDate || latestCommitDate < latestChangesRequestedDate) {
+        if (!isChangesAddressedByCommit(commitDate, latestChangesRequestedDate)) {
             return { status: 'needs_addressing', actionReason: 'needs_changes', stalenessTier };
         }
         // Commit is after review — changes have been addressed
@@ -93,9 +148,14 @@ export function determineStatus(input) {
         return { status: 'waiting_on_maintainer', waitReason: 'changes_addressed', stalenessTier };
     }
     if (ciStatus === 'failing') {
-        return hasActionableCIFailure
-            ? { status: 'needs_addressing', actionReason: 'failing_ci', stalenessTier }
-            : { status: 'waiting_on_maintainer', waitReason: 'ci_blocked', stalenessTier };
+        if (hasActionableCIFailure) {
+            // Demote stale CI failures: if failing for 5+ days with no activity, likely pre-existing (#675)
+            if (daysSinceActivity >= STALE_CI_DEMOTION_DAYS) {
+                return { status: 'waiting_on_maintainer', waitReason: 'stale_ci_failure', stalenessTier };
+            }
+            return { status: 'needs_addressing', actionReason: 'failing_ci', stalenessTier };
+        }
+        return { status: 'waiting_on_maintainer', waitReason: 'ci_blocked', stalenessTier };
     }
     if (hasMergeConflict) {
         return { status: 'needs_addressing', actionReason: 'merge_conflict', stalenessTier };

package/dist/core/types.d.ts

@@ -25,7 +25,7 @@ export interface ClassifiedCheck {
     category: CIFailureCategory;
     conclusion?: string;
 }
-/** Return type for PRMonitor.getCIStatus(). */
+/** CI status result returned by getCIStatus(). */
 export interface CIStatusResult {
     status: CIStatus;
     failingCheckNames: string[];
@@ -67,6 +67,8 @@ export interface DetermineStatusResult {
     actionReason?: ActionReason;
     waitReason?: WaitReason;
     stalenessTier: StalenessTier;
+    /** All applicable action reasons, ordered by priority. */
+    actionReasons?: ActionReason[];
 }
 /**
  * Granular reason why a PR needs addressing (contributor's turn).
@@ -77,7 +79,7 @@ export interface DetermineStatusResult {
  */
 export type ActionReason = 'needs_response' | 'needs_changes' | 'failing_ci' | 'merge_conflict' | 'incomplete_checklist' | 'ci_not_running' | 'needs_rebase' | 'missing_required_files';
 /** Granular reason why a PR is waiting on the maintainer. */
-export type WaitReason = 'pending_review' | 'pending_merge' | 'changes_addressed' | 'ci_blocked';
+export type WaitReason = 'pending_review' | 'pending_merge' | 'changes_addressed' | 'ci_blocked' | 'stale_ci_failure';
 /** How stale is the PR based on days since activity. Orthogonal to status. */
 export type StalenessTier = 'active' | 'approaching_dormant' | 'dormant';
 /**
@@ -110,6 +112,8 @@ export interface FetchedPR {
     actionReason?: ActionReason;
     /** Granular reason for waiting_on_maintainer status. Undefined when needs_addressing. */
     waitReason?: WaitReason;
+    /** All applicable action reasons, ordered by priority. Primary reason is first. */
+    actionReasons?: ActionReason[];
     /** How stale the PR is based on activity age. Independent of status — a PR can be both needs_addressing and dormant. */
     stalenessTier: StalenessTier;
     /** Human-readable status label for consistent display (#79). E.g., "[CI Failing]", "[Needs Response]". */
@@ -264,6 +268,8 @@ export interface RepoScore {
     signals: RepoSignals;
     /** GitHub star count, fetched during daily check for dashboard filtering. */
     stargazersCount?: number;
+    /** Primary programming language of the repo, fetched during daily check. */
+    language?: string | null;
 }
 /** Full set of qualitative signals about a repo's maintainer culture. */
 export interface RepoSignals {
@@ -285,6 +291,14 @@ export interface RepoScoreUpdate {
     lastMergedAt?: string;
     signals?: Partial<RepoSignals>;
     stargazersCount?: number;
+    /** Primary programming language of the repo. */
+    language?: string | null;
+}
+/** Repo metadata entry used in dashboard API responses. Shared between server and SPA. */
+export interface RepoMetadataEntry {
+    /** Star count, derived from RepoScore.stargazersCount. */
+    stars?: number;
+    language?: string | null;
 }
 /**
  * Event types recorded in the {@link AgentState} audit log.
@@ -454,6 +468,8 @@ export interface AgentConfig {
     languages: string[];
     /** GitHub labels to filter issues by (e.g., `["good first issue", "help wanted"]`). */
     labels: string[];
+    /** Issue scope tiers to search (e.g., `["beginner", "intermediate"]`). When set, scope tier labels are merged with custom `labels`. When absent, only `labels` is used (legacy behavior). */
+    scope?: IssueScope[];
     /** Repos to exclude from issue discovery/search, in `"owner/repo"` format. */
     excludeRepos: string[];
     /** Organizations to exclude from issue discovery/search (case-insensitive match on owner segment). */
@@ -484,6 +500,8 @@ export interface AgentConfig {
     dismissedIssues?: Record<string, string>;
     /** Manual status overrides for PRs. Maps PR URL to override metadata. Auto-clears when the PR has new activity. */
     statusOverrides?: Record<string, StatusOverride>;
+    /** Path to the user's curated issue list file. Replaces config.md as the primary source for detectIssueList(). */
+    issueListPath?: string;
     /** Project categories the user is interested in (e.g., devtools, nonprofit). Used to prioritize search results. */
     projectCategories?: ProjectCategory[];
     /** GitHub organizations the user wants to prioritize in issue search. Org names only (not owner/repo). */
@@ -528,6 +546,9 @@ export declare const DEFAULT_CONFIG: AgentConfig;
 export declare const INITIAL_STATE: AgentState;
 export declare const PROJECT_CATEGORIES: readonly ["nonprofit", "devtools", "infrastructure", "web-frameworks", "data-ml", "education"];
 export type ProjectCategory = (typeof PROJECT_CATEGORIES)[number];
+export declare const ISSUE_SCOPES: readonly ["beginner", "intermediate", "advanced"];
+export type IssueScope = (typeof ISSUE_SCOPES)[number];
+export declare const SCOPE_LABELS: Record<IssueScope, string[]>;
 /** Priority tier for issue search results. Ordered: merged_pr > preferred_org > starred > normal. */
 export type SearchPriority = 'merged_pr' | 'preferred_org' | 'starred' | 'normal';
 export interface IssueCandidate {

package/dist/core/types.js

@@ -49,3 +49,10 @@ export const PROJECT_CATEGORIES = [
     'data-ml',
     'education',
 ];
+// -- Issue scope types --
+export const ISSUE_SCOPES = ['beginner', 'intermediate', 'advanced'];
+export const SCOPE_LABELS = {
+    beginner: ['good first issue', 'help wanted', 'easy', 'up-for-grabs', 'first-timers-only', 'beginner'],
+    intermediate: ['enhancement', 'feature', 'feature-request', 'contributions welcome'],
+    advanced: ['proposal', 'RFC', 'accepted', 'design'],
+};

package/dist/formatters/json.d.ts

@@ -5,7 +5,7 @@
 import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, ShelvedPRRef } from '../core/types.js';
 import type { ContributionStats } from '../core/stats.js';
 import type { PRCheckFailure } from '../core/pr-monitor.js';
-import type { SearchPriority } from '../core/issue-discovery.js';
+import type { SearchPriority } from '../core/types.js';
 export interface JsonOutput<T = unknown> {
     success: boolean;
     data?: T;

package/package.json

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