@oss-autopilot/core 0.41.0

package/dist/core/review-analysis.js

@@ -0,0 +1,163 @@
+/**
+ * Review Analysis - Review decision computation, unresponded comment detection,
+ * and self-reply filtering for PR reviews.
+ * Extracted from PRMonitor to isolate review-related logic (#263).
+ */
+import { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
+/**
+ * Determine review decision from reviews list.
+ * Groups reviews by user, keeping only the latest from each user,
+ * then checks for CHANGES_REQUESTED or APPROVED states.
+ */
+export function determineReviewDecision(reviews) {
+    if (reviews.length === 0) {
+        return 'review_required';
+    }
+    // Group reviews by user, keeping only the latest from each user
+    const latestByUser = new Map();
+    for (const review of reviews) {
+        const login = review.user?.login;
+        const state = review.state;
+        if (login && state) {
+            latestByUser.set(login, state);
+        }
+    }
+    const states = Array.from(latestByUser.values());
+    if (states.includes('CHANGES_REQUESTED')) {
+        return 'changes_requested';
+    }
+    if (states.includes('APPROVED')) {
+        return 'approved';
+    }
+    return 'review_required';
+}
+/**
+ * Get the date of the latest CHANGES_REQUESTED review (from any reviewer).
+ * Used to detect needs_changes status when review feedback is in inline comments.
+ */
+export function getLatestChangesRequestedDate(reviews) {
+    let latest;
+    for (const review of reviews) {
+        if (review.state === 'CHANGES_REQUESTED' && review.submitted_at) {
+            if (!latest || review.submitted_at > latest) {
+                latest = review.submitted_at;
+            }
+        }
+    }
+    return latest;
+}
+/**
+ * Check if all inline comments in a COMMENTED review are self-replies.
+ * A self-reply is when an author replies to their own earlier inline comment.
+ * Used to filter out informational follow-ups that don't require contributor action (#199).
+ */
+export function isAllSelfReplies(reviewId, reviewComments) {
+    const commentsForReview = reviewComments.filter((c) => c.pull_request_review_id === reviewId);
+    if (commentsForReview.length === 0)
+        return false;
+    // Build map of ALL comment IDs -> lowercase author for parent lookup
+    const authorMap = new Map();
+    for (const c of reviewComments) {
+        if (c.user?.login) {
+            authorMap.set(c.id, c.user.login.toLowerCase());
+        }
+    }
+    return commentsForReview.every((comment) => {
+        if (!comment.in_reply_to_id)
+            return false; // New thread, not a reply
+        const parentAuthor = authorMap.get(comment.in_reply_to_id);
+        const commentAuthor = comment.user?.login?.toLowerCase();
+        return parentAuthor != null && commentAuthor != null && parentAuthor === commentAuthor;
+    });
+}
+/**
+ * Get the body text of inline review comments for a COMMENTED review.
+ * Returns the first non-empty comment body, or undefined.
+ * Enables the acknowledgment filter to evaluate real content instead of
+ * synthetic placeholders (#199).
+ */
+export function getInlineCommentBody(reviewId, reviewComments) {
+    return reviewComments.find((c) => c.pull_request_review_id === reviewId && c.body?.trim())?.body?.trim();
+}
+/**
+ * Check if there are unresponded comments from maintainers.
+ * Combines issue comments and review comments into a timeline,
+ * then finds maintainer comments after the user's last comment.
+ */
+export function checkUnrespondedComments(comments, reviews, reviewComments, username) {
+    // Combine comments and reviews into a timeline
+    const timeline = [];
+    const usernameLower = username.toLowerCase();
+    for (const comment of comments) {
+        const author = comment.user?.login || 'unknown';
+        timeline.push({
+            author,
+            body: comment.body || '',
+            createdAt: comment.created_at,
+            isUser: author.toLowerCase() === usernameLower,
+        });
+    }
+    for (const review of reviews) {
+        if (!review.submitted_at)
+            continue;
+        const body = (review.body || '').trim();
+        // Include COMMENTED reviews even without body text — they indicate
+        // inline review comments were posted and may need a response (#151).
+        // Skip other empty-body reviews (APPROVED, CHANGES_REQUESTED, DISMISSED)
+        // as those are state changes without comment text.
+        if (!body && review.state !== 'COMMENTED')
+            continue;
+        const author = review.user?.login || 'unknown';
+        // For inline-only COMMENTED reviews, skip pure self-replies (#199)
+        if (!body && review.state === 'COMMENTED' && review.id != null) {
+            if (isAllSelfReplies(review.id, reviewComments)) {
+                continue;
+            }
+        }
+        // Resolve body: prefer actual text, then inline comment text, then synthetic placeholder
+        const resolvedBody = body ||
+            (review.id != null ? getInlineCommentBody(review.id, reviewComments) : undefined) ||
+            '(posted inline review comments)';
+        timeline.push({
+            author,
+            body: resolvedBody,
+            createdAt: review.submitted_at,
+            isUser: author.toLowerCase() === usernameLower,
+        });
+    }
+    // Sort by date
+    timeline.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+    // Find the last user comment
+    let lastUserCommentTime = null;
+    for (const item of timeline) {
+        if (item.isUser) {
+            lastUserCommentTime = new Date(item.createdAt);
+        }
+    }
+    // Find maintainer comments after the user's last comment
+    let lastMaintainerComment;
+    for (const item of timeline) {
+        if (item.isUser)
+            continue; // Skip user's own comments
+        if (item.author === 'unknown')
+            continue; // Skip deleted/null accounts
+        if (isBotAuthor(item.author))
+            continue; // Skip bots
+        const itemTime = new Date(item.createdAt);
+        if (!lastUserCommentTime || itemTime > lastUserCommentTime) {
+            lastMaintainerComment = {
+                author: item.author,
+                body: item.body.slice(0, 200) + (item.body.length > 200 ? '...' : ''),
+                createdAt: item.createdAt,
+            };
+        }
+    }
+    // Filter out pure acknowledgment comments that don't require a response
+    if (lastMaintainerComment && isAcknowledgmentComment(lastMaintainerComment.body)) {
+        lastMaintainerComment = undefined;
+    }
+    return {
+        hasUnrespondedComment: !!lastMaintainerComment,
+        lastMaintainerComment,
+    };
+}

package/dist/core/state.d.ts

@@ -0,0 +1,371 @@
+/**
+ * State management for the OSS Contribution Agent
+ * Persists state to a JSON file in ~/.oss-autopilot/
+ */
+import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, SnoozeInfo } 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;
+/**
+ * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
+ *
+ * Handles loading, saving, backup/restore, and v1-to-v2 migration of state. Supports
+ * an in-memory mode (no disk I/O) for use in tests. In v2 architecture, PR arrays are
+ * legacy -- open PRs are fetched fresh from GitHub on each run rather than stored locally.
+ */
+export declare class StateManager {
+    private state;
+    private readonly inMemoryOnly;
+    /**
+     * Create a new StateManager instance.
+     * @param inMemoryOnly - When true, state is held only in memory and never read from or
+     *   written to disk. Useful for unit tests that need isolated state without side effects.
+     *   Defaults to false (normal persistent mode).
+     */
+    constructor(inMemoryOnly?: boolean);
+    /**
+     * Create a fresh state (v2: fresh GitHub fetching)
+     */
+    private createFreshState;
+    /**
+     * Check if initial setup has been completed.
+     * @returns true if the user has run `/setup-oss` and completed configuration.
+     */
+    isSetupComplete(): boolean;
+    /**
+     * Mark setup as complete and record the completion timestamp.
+     */
+    markSetupComplete(): void;
+    /**
+     * Migrate state from legacy ./data/ location to ~/.oss-autopilot/
+     * Returns true if migration was performed
+     */
+    private migrateFromLegacyLocation;
+    /**
+     * 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.
+     */
+    private load;
+    /**
+     * Attempt to restore state from the most recent valid backup.
+     * Returns the restored state if successful, or null if no valid backup is found.
+     */
+    private tryRestoreFromBackup;
+    /**
+     * Validate that a loaded state has the required structure
+     * Handles both v1 (with PR arrays) and v2 (without)
+     */
+    private isValidState;
+    /**
+     * Persist the current state to disk, creating a timestamped backup of the previous
+     * state file first. Updates `lastRunAt` to the current time. In in-memory mode,
+     * only updates `lastRunAt` without any file I/O. Retains at most 10 backup files.
+     */
+    save(): void;
+    private cleanupBackups;
+    /**
+     * Get the current state as a read-only snapshot.
+     * @returns The full agent state. Callers should not mutate the returned object;
+     *   use the StateManager methods to make changes.
+     */
+    getState(): Readonly<AgentState>;
+    /**
+     * Store the latest daily digest for dashboard rendering.
+     * @param digest - The freshly generated digest from the current daily run.
+     */
+    setLastDigest(digest: DailyDigest): void;
+    /**
+     * Store monthly merged PR counts for the contribution timeline chart.
+     * @param counts - Map of "YYYY-MM" strings to merged PR counts for that month.
+     */
+    setMonthlyMergedCounts(counts: Record<string, number>): void;
+    /**
+     * Store monthly closed (without merge) PR counts for the contribution timeline and success rate charts.
+     * @param counts - Map of "YYYY-MM" strings to closed PR counts for that month.
+     */
+    setMonthlyClosedCounts(counts: Record<string, number>): void;
+    /**
+     * Store monthly opened PR counts for the contribution timeline chart.
+     * @param counts - Map of "YYYY-MM" strings to opened PR counts for that month.
+     */
+    setMonthlyOpenedCounts(counts: Record<string, number>): void;
+    setDailyActivityCounts(counts: Record<string, number>): void;
+    /**
+     * Store cached local repo scan results (#84).
+     * @param cache - The scan results, paths scanned, and timestamp.
+     */
+    setLocalRepoCache(cache: LocalRepoCache): void;
+    /**
+     * Shallow-merge partial configuration updates into the current config.
+     * @param config - Partial config object whose properties override existing values.
+     */
+    updateConfig(config: Partial<AgentState['config']>): void;
+    /**
+     * Append an event to the event log. Events are capped at {@link MAX_EVENTS} (1000);
+     * when the cap is exceeded, the oldest events are trimmed to stay within the limit.
+     * @param type - The event type (e.g. 'pr_tracked').
+     * @param data - Arbitrary key-value payload for the event.
+     */
+    appendEvent(type: StateEventType, data: Record<string, unknown>): void;
+    /**
+     * Filter the event log to events of a specific type.
+     * @param type - The event type to filter by.
+     * @returns All events matching the given type, in chronological order.
+     */
+    getEventsByType(type: StateEventType): StateEvent[];
+    /**
+     * Filter the event log to events within an inclusive time range.
+     * @param since - Start of the range (inclusive).
+     * @param until - End of the range (inclusive). Defaults to now.
+     * @returns Events whose timestamps fall within [since, until].
+     */
+    getEventsInRange(since: Date, until?: Date): StateEvent[];
+    /**
+     * Add an issue to the active tracking list. If an issue with the same URL is
+     * already tracked, the call is a no-op.
+     * @param issue - The issue to begin tracking.
+     */
+    addIssue(issue: TrackedIssue): void;
+    /**
+     * Add a repository to the trusted projects list. Trusted projects are prioritized
+     * in issue search results. No-op if the repo is already trusted.
+     * @param repo - Repository in "owner/repo" format.
+     */
+    addTrustedProject(repo: string): void;
+    /**
+     * Test whether a repo matches any of the given exclusion lists.
+     * Both repo and org comparisons are case-insensitive (GitHub names are case-insensitive).
+     * @param repo  - Repository in "owner/repo" format.
+     * @param repos - Full "owner/repo" strings (case-insensitive match).
+     * @param orgs  - Org names (case-insensitive match against the owner segment of the repo).
+     */
+    private static matchesExclusion;
+    /**
+     * Check whether a repository matches any exclusion rule from the current config.
+     * A repo is excluded if it matches an entry in `excludeRepos` (case-insensitive)
+     * or if its owner segment matches an entry in `excludeOrgs` (case-insensitive).
+     * @param repo - Repository in "owner/repo" format.
+     */
+    private isExcluded;
+    /**
+     * Remove repositories matching the given exclusion lists from `trustedProjects`
+     * and `repoScores`. Called when a repo or org is newly excluded to keep stored
+     * data consistent with current filters.
+     * @param repos - Full "owner/repo" strings to exclude (case-insensitive match).
+     * @param orgs  - Org names to exclude (case-insensitive match against owner segment).
+     */
+    cleanupExcludedData(repos: string[], orgs: string[]): void;
+    /**
+     * Get the cached list of the user's GitHub starred repositories.
+     * @returns Array of "owner/repo" strings, or an empty array if never fetched.
+     */
+    getStarredRepos(): string[];
+    /**
+     * Replace the cached starred repositories list and update the fetch timestamp.
+     * @param repos - Array of "owner/repo" strings from the user's GitHub stars.
+     */
+    setStarredRepos(repos: string[]): void;
+    /**
+     * Check if the starred repos cache is stale (older than 24 hours) or has never been fetched.
+     * @returns true if the cache should be refreshed.
+     */
+    isStarredReposStale(): boolean;
+    /**
+     * Shelve a PR by URL. Shelved PRs are excluded from capacity and actionable issues.
+     * They are auto-unshelved when a maintainer engages (needs_response, needs_changes, etc.).
+     * @param url - The full GitHub PR URL.
+     * @returns true if newly added, false if already shelved.
+     */
+    shelvePR(url: string): boolean;
+    /**
+     * Unshelve a PR by URL.
+     * @param url - The full GitHub PR URL.
+     * @returns true if found and removed, false if not shelved.
+     */
+    unshelvePR(url: string): boolean;
+    /**
+     * Check if a PR is shelved.
+     * @param url - The full GitHub PR URL.
+     * @returns true if the URL is in the shelved list.
+     */
+    isPRShelved(url: string): boolean;
+    /**
+     * Dismiss an issue by URL. Dismissed issues are excluded from `new_response` notifications
+     * until new activity occurs after the dismiss timestamp.
+     * @param url - The full GitHub issue URL.
+     * @param timestamp - ISO timestamp of when the issue was dismissed.
+     * @returns true if newly dismissed, false if already dismissed.
+     */
+    dismissIssue(url: string, timestamp: string): boolean;
+    /**
+     * Undismiss an issue by URL.
+     * @param url - The full GitHub issue URL.
+     * @returns true if found and removed, false if not dismissed.
+     */
+    undismissIssue(url: string): boolean;
+    /**
+     * Get the timestamp when an issue was dismissed.
+     * @param url - The full GitHub issue URL.
+     * @returns The ISO dismiss timestamp, or undefined if not dismissed.
+     */
+    getIssueDismissedAt(url: string): string | undefined;
+    /**
+     * Snooze a PR's CI failure for a given number of days.
+     * Snoozed PRs are excluded from actionable CI failure lists until the snooze expires.
+     * @param url - The full GitHub PR URL.
+     * @param reason - Why the CI failure is being snoozed (e.g., "upstream infrastructure issue").
+     * @param durationDays - Number of days to snooze. Default 7.
+     * @returns true if newly snoozed, false if already snoozed.
+     */
+    snoozePR(url: string, reason: string, durationDays: number): boolean;
+    /**
+     * Unsnooze a PR by URL.
+     * @param url - The full GitHub PR URL.
+     * @returns true if found and removed, false if not snoozed.
+     */
+    unsnoozePR(url: string): boolean;
+    /**
+     * Check if a PR is currently snoozed (not expired).
+     * @param url - The full GitHub PR URL.
+     * @returns true if the PR is snoozed and the snooze has not expired.
+     */
+    isSnoozed(url: string): boolean;
+    /**
+     * Get snooze metadata for a PR.
+     * @param url - The full GitHub PR URL.
+     * @returns The snooze metadata, or undefined if not snoozed.
+     */
+    getSnoozeInfo(url: string): SnoozeInfo | undefined;
+    /**
+     * Expire all snoozes that are past their `expiresAt` timestamp.
+     * @returns Array of PR URLs whose snoozes were expired.
+     */
+    expireSnoozes(): string[];
+    /**
+     * Get the score record for a repository.
+     * @param repo - Repository in "owner/repo" format.
+     * @returns The RepoScore if the repo has been scored, or undefined if never evaluated.
+     */
+    getRepoScore(repo: string): RepoScore | undefined;
+    /**
+     * Create a default repo score for a new repository
+     */
+    private createDefaultRepoScore;
+    /**
+     * 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.
+     */
+    private calculateScore;
+    /**
+     * 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 using the formula: base 5, logarithmic merge bonus (max +5),
+     * -1 per closed-without-merge (max -3), +1 if recently merged, +1 if responsive, -2 if hostile, clamped to [1, 10].
+     * @param repo - Repository in "owner/repo" format.
+     * @param updates - Updatable RepoScore fields to merge. The `score`, `repo`, and
+     *   `lastEvaluatedAt` fields are not accepted — score is always derived via
+     *   calculateScore(), and repo/lastEvaluatedAt are managed internally.
+     */
+    updateRepoScore(repo: string, updates: RepoScoreUpdate): void;
+    /**
+     * Increment the merged PR count for a repository and recalculate its score.
+     * Routes through {@link updateRepoScore} for a single mutation path.
+     * @param repo - Repository in "owner/repo" format.
+     */
+    incrementMergedCount(repo: string): void;
+    /**
+     * Increment the closed-without-merge count for a repository and recalculate its score.
+     * Routes through {@link updateRepoScore} for a single mutation path.
+     * @param repo - Repository in "owner/repo" format.
+     */
+    incrementClosedCount(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.
+     * @param repo - Repository in "owner/repo" format.
+     */
+    markRepoHostile(repo: string): void;
+    /**
+     * Get repositories where the user has at least one merged PR, sorted by merged count descending.
+     * These repos represent proven relationships with high merge probability.
+     * @returns Array of "owner/repo" strings for repos with mergedPRCount > 0.
+     */
+    getReposWithMergedPRs(): string[];
+    /**
+     * Get repositories where the user has interacted (has a score record) but has NOT
+     * yet had a PR merged, excluding repos where the only interaction was rejection.
+     * These represent repos with open or in-progress PRs — relationships that benefit
+     * from continued search attention.
+     * @returns Array of "owner/repo" strings, sorted by score descending.
+     */
+    getReposWithOpenPRs(): string[];
+    /**
+     * Get repositories with a score at or above the given threshold, sorted highest first.
+     * @param minScore - Minimum score (inclusive). Defaults to `config.minRepoScoreThreshold`.
+     * @returns Array of "owner/repo" strings for repos meeting the threshold.
+     */
+    getHighScoringRepos(minScore?: number): string[];
+    /**
+     * Get repositories with a score at or below the given threshold, sorted lowest first.
+     * @param maxScore - Maximum score (inclusive). Defaults to `config.minRepoScoreThreshold`.
+     * @returns Array of "owner/repo" strings for repos at or below the threshold.
+     */
+    getLowScoringRepos(maxScore?: number): string[];
+    /**
+     * Compute aggregate statistics from the current state. `mergedPRs` and `closedPRs` counts
+     * are summed from repo score records, excluding repos that match `excludeRepos` or `excludeOrgs`
+     * in the config (#211). `totalTracked` reflects the number of non-excluded repositories with
+     * score records.
+     * @returns A Stats snapshot computed from the current state.
+     */
+    getStats(): Stats;
+}
+/**
+ * Aggregate statistics returned by {@link StateManager.getStats}.
+ */
+export interface Stats {
+    /** Total merged PRs across scored repositories (excludes repos/orgs in exclusion config). */
+    mergedPRs: number;
+    /** Total PRs closed without merge across scored repositories (excludes repos/orgs in exclusion config). */
+    closedPRs: number;
+    /** Number of active issues. Always 0 in v2 (sourced from fresh fetch instead). */
+    activeIssues: number;
+    /** Number of trusted projects (excludes repos/orgs in exclusion config). */
+    trustedProjects: number;
+    /** Merge success rate as a percentage string (e.g. "75.0%"). */
+    mergeRate: string;
+    /** Number of scored repositories (excludes repos/orgs in exclusion config). */
+    totalTracked: number;
+    /** Number of PRs needing a response. Always 0 in v2 (sourced from fresh fetch instead). */
+    needsResponse: number;
+}
+/**
+ * Get the singleton StateManager instance, creating it on first call.
+ * Subsequent calls return the same instance. Use {@link resetStateManager} to
+ * clear the singleton (primarily for testing).
+ * @returns The shared StateManager instance.
+ */
+export declare function getStateManager(): StateManager;
+/**
+ * Reset the singleton StateManager instance to null. The next call to
+ * {@link getStateManager} will create a fresh instance. Intended for test
+ * isolation -- should not be called in production code.
+ */
+export declare function resetStateManager(): void;