@oss-autopilot/core 0.51.1 → 0.52.0

package/dist/core/index.d.ts

@@ -2,7 +2,7 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, resetStateManager } from './state.js';
+export { StateManager, getStateManager, resetStateManager, type Stats } from './state.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 export { IssueDiscovery, type IssueCandidate, type SearchPriority, isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS, } from './issue-discovery.js';
 export { IssueConversationMonitor } from './issue-conversation.js';

package/dist/core/repo-score-manager.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Repository scoring logic for the OSS Contribution Agent.
+ * Functions that operate on AgentState for scoring, querying,
+ * and computing aggregate statistics. Mutation functions modify
+ * the passed state object in place; query functions are pure.
+ */
+import { AgentState, RepoScore, RepoScoreUpdate } from './types.js';
+/**
+ * Calculate the score based on the repo's metrics.
+ * Base 5, logarithmic merge bonus (max +5), -1 per closed without merge (max -3),
+ * +1 if recently merged (within 90 days), +1 if responsive, -2 if hostile. Clamp 1-10.
+ */
+export declare function calculateScore(repoScore: RepoScore): number;
+/**
+ * Get the score record for a repository.
+ */
+export declare function getRepoScore(state: Readonly<AgentState>, repo: string): Readonly<RepoScore> | undefined;
+/**
+ * Update a repository's score with partial updates. If the repo has no existing score,
+ * a default score record is created first (base score 5). After applying updates, the
+ * numeric score is recalculated.
+ */
+export declare function updateRepoScore(state: AgentState, repo: string, updates: RepoScoreUpdate): void;
+/**
+ * Increment the merged PR count for a repository and recalculate its score.
+ */
+export declare function incrementMergedCount(state: AgentState, repo: string): void;
+/**
+ * Increment the closed-without-merge count for a repository and recalculate its score.
+ */
+export declare function incrementClosedCount(state: AgentState, repo: string): void;
+/**
+ * Mark a repository as having hostile maintainer comments and recalculate its score.
+ * This applies a -2 penalty to the score. Creates a default score record if needed.
+ */
+export declare function markRepoHostile(state: AgentState, repo: string): void;
+/**
+ * Get repositories where the user has at least one merged PR, sorted by merged count descending.
+ */
+export declare function getReposWithMergedPRs(state: Readonly<AgentState>): string[];
+/**
+ * Get repositories with a score record but no merge or closure outcomes yet
+ * (typically repos with only open PRs), sorted by score descending.
+ */
+export declare function getReposWithOpenPRs(state: Readonly<AgentState>): string[];
+/**
+ * Get repositories with a score at or above the given threshold, sorted highest first.
+ */
+export declare function getHighScoringRepos(state: Readonly<AgentState>, minScore?: number): string[];
+/**
+ * Get repositories with a score at or below the given threshold, sorted lowest first.
+ */
+export declare function getLowScoringRepos(state: Readonly<AgentState>, maxScore?: number): string[];
+/**
+ * Aggregate statistics returned by {@link getStats}.
+ */
+export interface Stats {
+    /** Total merged PRs across scored repositories (above minStars threshold). */
+    mergedPRs: number;
+    /** Total PRs closed without merge across scored repositories (above minStars threshold). */
+    closedPRs: number;
+    /** Number of active issues. Always 0 in v2 (sourced from fresh fetch instead). */
+    activeIssues: number;
+    /** Number of trusted projects. */
+    trustedProjects: number;
+    /** Merge success rate as a percentage string (e.g. "75.0%"). */
+    mergeRate: string;
+    /** Number of scored repositories (above minStars threshold). */
+    totalTracked: number;
+    /** Number of PRs needing a response. Always 0 in v2 (sourced from fresh fetch instead). */
+    needsResponse: number;
+}
+/**
+ * Compute aggregate statistics from the current state.
+ */
+export declare function getStats(state: Readonly<AgentState>): Stats;

package/dist/core/repo-score-manager.js

@@ -0,0 +1,204 @@
+/**
+ * Repository scoring logic for the OSS Contribution Agent.
+ * Functions that operate on AgentState for scoring, querying,
+ * and computing aggregate statistics. Mutation functions modify
+ * the passed state object in place; query functions are pure.
+ */
+import { isBelowMinStars } from './types.js';
+import { debug, warn } from './logger.js';
+const MODULE = 'scoring';
+/** Repo scores older than this are considered stale and excluded from low-scoring lists. */
+const SCORE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/**
+ * Create a default repo score for a new repository.
+ */
+function createDefaultRepoScore(repo) {
+    return {
+        repo,
+        score: 5, // Base score
+        mergedPRCount: 0,
+        closedWithoutMergeCount: 0,
+        avgResponseDays: null,
+        lastEvaluatedAt: new Date().toISOString(),
+        signals: {
+            hasActiveMaintainers: true, // Assume positive by default
+            isResponsive: false,
+            hasHostileComments: false,
+        },
+    };
+}
+/**
+ * Calculate the score based on the repo's metrics.
+ * Base 5, logarithmic merge bonus (max +5), -1 per closed without merge (max -3),
+ * +1 if recently merged (within 90 days), +1 if responsive, -2 if hostile. Clamp 1-10.
+ */
+export function calculateScore(repoScore) {
+    let score = 5; // Base score
+    // Logarithmic merge bonus (max +5): 1→+2, 2→+3, 3→+4, 4+→+5
+    if (repoScore.mergedPRCount > 0) {
+        const mergedBonus = Math.min(Math.round(Math.log2(repoScore.mergedPRCount + 1) * 2), 5);
+        score += mergedBonus;
+    }
+    // -1 per closed without merge (max -3)
+    const closedPenalty = Math.min(repoScore.closedWithoutMergeCount, 3);
+    score -= closedPenalty;
+    // +1 if lastMergedAt is set and within 90 days (recency)
+    if (repoScore.lastMergedAt) {
+        const lastMergedDate = new Date(repoScore.lastMergedAt);
+        if (isNaN(lastMergedDate.getTime())) {
+            warn(MODULE, `Invalid lastMergedAt date for ${repoScore.repo}: "${repoScore.lastMergedAt}". Skipping recency bonus.`);
+        }
+        else {
+            const msPerDay = 1000 * 60 * 60 * 24;
+            const daysSince = Math.floor((Date.now() - lastMergedDate.getTime()) / msPerDay);
+            if (daysSince <= 90) {
+                score += 1;
+            }
+        }
+    }
+    // +1 if responsive
+    if (repoScore.signals.isResponsive) {
+        score += 1;
+    }
+    // -2 if hostile
+    if (repoScore.signals.hasHostileComments) {
+        score -= 2;
+    }
+    // Clamp to 1-10
+    return Math.max(1, Math.min(10, score));
+}
+/**
+ * Get the score record for a repository.
+ */
+export function getRepoScore(state, repo) {
+    return state.repoScores[repo];
+}
+/**
+ * Update a repository's score with partial updates. If the repo has no existing score,
+ * a default score record is created first (base score 5). After applying updates, the
+ * numeric score is recalculated.
+ */
+export function updateRepoScore(state, repo, updates) {
+    if (!state.repoScores[repo]) {
+        state.repoScores[repo] = createDefaultRepoScore(repo);
+    }
+    const repoScore = state.repoScores[repo];
+    // Apply explicit field updates (skip undefined values to preserve existing data)
+    if (updates.mergedPRCount !== undefined)
+        repoScore.mergedPRCount = updates.mergedPRCount;
+    if (updates.closedWithoutMergeCount !== undefined)
+        repoScore.closedWithoutMergeCount = updates.closedWithoutMergeCount;
+    if (updates.avgResponseDays !== undefined)
+        repoScore.avgResponseDays = updates.avgResponseDays;
+    if (updates.lastMergedAt !== undefined)
+        repoScore.lastMergedAt = updates.lastMergedAt;
+    if (updates.stargazersCount !== undefined)
+        repoScore.stargazersCount = updates.stargazersCount;
+    if (updates.signals) {
+        repoScore.signals = { ...repoScore.signals, ...updates.signals };
+    }
+    // Recalculate score
+    repoScore.score = calculateScore(repoScore);
+    repoScore.lastEvaluatedAt = new Date().toISOString();
+    debug(MODULE, `Updated repo score for ${repo}: ${repoScore.score}/10`);
+}
+/**
+ * Increment the merged PR count for a repository and recalculate its score.
+ */
+export function incrementMergedCount(state, repo) {
+    const newCount = (state.repoScores[repo]?.mergedPRCount ?? 0) + 1;
+    updateRepoScore(state, repo, {
+        mergedPRCount: newCount,
+        lastMergedAt: new Date().toISOString(),
+    });
+}
+/**
+ * Increment the closed-without-merge count for a repository and recalculate its score.
+ */
+export function incrementClosedCount(state, repo) {
+    const newCount = (state.repoScores[repo]?.closedWithoutMergeCount ?? 0) + 1;
+    updateRepoScore(state, repo, { closedWithoutMergeCount: newCount });
+}
+/**
+ * Mark a repository as having hostile maintainer comments and recalculate its score.
+ * This applies a -2 penalty to the score. Creates a default score record if needed.
+ */
+export function markRepoHostile(state, repo) {
+    updateRepoScore(state, repo, { signals: { hasHostileComments: true } });
+}
+/**
+ * Get repositories where the user has at least one merged PR, sorted by merged count descending.
+ */
+export function getReposWithMergedPRs(state) {
+    return Object.values(state.repoScores)
+        .filter((rs) => rs.mergedPRCount > 0)
+        .sort((a, b) => b.mergedPRCount - a.mergedPRCount)
+        .map((rs) => rs.repo);
+}
+/**
+ * Get repositories with a score record but no merge or closure outcomes yet
+ * (typically repos with only open PRs), sorted by score descending.
+ */
+export function getReposWithOpenPRs(state) {
+    return Object.values(state.repoScores)
+        .filter((rs) => rs.mergedPRCount === 0 && rs.closedWithoutMergeCount === 0)
+        .sort((a, b) => b.score - a.score)
+        .map((rs) => rs.repo);
+}
+/**
+ * Get repositories with a score at or above the given threshold, sorted highest first.
+ */
+export function getHighScoringRepos(state, minScore) {
+    const threshold = minScore ?? state.config.minRepoScoreThreshold;
+    return Object.values(state.repoScores)
+        .filter((rs) => rs.score >= threshold)
+        .sort((a, b) => b.score - a.score)
+        .map((rs) => rs.repo);
+}
+/**
+ * Get repositories with a score at or below the given threshold, sorted lowest first.
+ */
+export function getLowScoringRepos(state, maxScore) {
+    const threshold = maxScore ?? state.config.minRepoScoreThreshold;
+    const now = Date.now();
+    return Object.values(state.repoScores)
+        .filter((rs) => {
+        if (rs.score > threshold)
+            return false;
+        // Stale scores (>30 days) should not permanently block repos (#487)
+        const age = now - new Date(rs.lastEvaluatedAt).getTime();
+        if (!Number.isFinite(age)) {
+            warn(MODULE, `Invalid lastEvaluatedAt for repo ${rs.repo}: "${rs.lastEvaluatedAt}", treating as stale`);
+            return false;
+        }
+        return age <= SCORE_TTL_MS;
+    })
+        .sort((a, b) => a.score - b.score)
+        .map((rs) => rs.repo);
+}
+/**
+ * Compute aggregate statistics from the current state.
+ */
+export function getStats(state) {
+    let totalMerged = 0;
+    let totalClosed = 0;
+    let totalTracked = 0;
+    for (const score of Object.values(state.repoScores)) {
+        if (isBelowMinStars(score.stargazersCount, state.config.minStars ?? 50))
+            continue;
+        totalTracked++;
+        totalMerged += score.mergedPRCount;
+        totalClosed += score.closedWithoutMergeCount;
+    }
+    const completed = totalMerged + totalClosed;
+    const mergeRate = completed > 0 ? (totalMerged / completed) * 100 : 0;
+    return {
+        mergedPRs: totalMerged,
+        closedPRs: totalClosed,
+        activeIssues: 0,
+        trustedProjects: state.config.trustedProjects.length,
+        mergeRate: mergeRate.toFixed(1) + '%',
+        totalTracked,
+        needsResponse: 0,
+    };
+}

package/dist/core/state-persistence.d.ts

@@ -0,0 +1,53 @@
+/**
+ * State persistence layer for the OSS Contribution Agent.
+ * Handles file I/O, locking, backup/restore, and v1-to-v2 migration.
+ * No module-level mutable state — functions accept/return AgentState objects.
+ */
+import { AgentState } from './types.js';
+/**
+ * Acquire an advisory file lock using exclusive-create (`wx` flag).
+ * If the lock file already exists but is stale (older than LOCK_TIMEOUT_MS or corrupt),
+ * it is removed and re-acquired.
+ * @throws Error if the lock is held by another active process.
+ */
+export declare function acquireLock(lockPath: string): void;
+/**
+ * Release an advisory file lock, but only if this process owns it.
+ * Silently ignores missing lock files or locks owned by other processes.
+ */
+export declare function releaseLock(lockPath: string): void;
+/**
+ * Write data to `filePath` atomically by first writing to a temporary file
+ * in the same directory and then renaming. Rename is atomic on POSIX filesystems,
+ * preventing partial/corrupt state files if the process crashes mid-write.
+ */
+export declare function atomicWriteFileSync(filePath: string, data: string, mode?: number): void;
+/**
+ * Create a fresh state (v2: fresh GitHub fetching).
+ */
+export declare function createFreshState(): AgentState;
+/**
+ * Load state from file, or create initial state if none exists.
+ * If the main state file is corrupted, attempts to restore from the most recent backup.
+ * Performs migration from legacy ./data/ location if needed.
+ * @returns Object with the loaded state and the file's mtime (for change detection).
+ */
+export declare function loadState(): {
+    state: AgentState;
+    mtimeMs: number;
+};
+/**
+ * Persist state to disk, creating a timestamped backup of the previous
+ * state file first. Retains at most 10 backup files.
+ * @returns The file's mtime after writing (for change detection).
+ */
+export declare function saveState(state: Readonly<AgentState>): number;
+/**
+ * Re-read state from disk if the file has been modified since the last load/save.
+ * Uses mtime comparison (single statSync call) to avoid unnecessary JSON parsing.
+ * @returns The new state and mtime if reloaded, or null if no change detected.
+ */
+export declare function reloadStateIfChanged(lastLoadedMtimeMs: number): {
+    state: AgentState;
+    mtimeMs: number;
+} | null;