@oss-autopilot/core 0.58.0 → 0.59.0

package/dist/core/logger.d.ts

@@ -9,18 +9,31 @@ export declare function enableDebug(): void;
 export declare function isDebugEnabled(): boolean;
 /**
  * Log a debug message. Only outputs when --debug is enabled.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export declare function debug(module: string, message: string, ...args: unknown[]): void;
 /**
  * Log an informational message. Always outputs to stderr.
  * Use for user-facing progress indicators during long-running operations.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export declare function info(module: string, message: string, ...args: unknown[]): void;
 /**
  * Log a warning. Always outputs.
+ * @param module - Module name for log prefix
+ * @param message - Warning message
+ * @param args - Additional values to log
  */
 export declare function warn(module: string, message: string, ...args: unknown[]): void;
 /**
  * Time an async operation and log duration in debug mode.
+ * @param module - Module name for log prefix
+ * @param label - Operation label for the timing log
+ * @param fn - Async function to time
+ * @returns The result of the async function
  */
 export declare function timed<T>(module: string, label: string, fn: () => Promise<T>): Promise<T>;

package/dist/core/logger.js

@@ -14,6 +14,9 @@ export function isDebugEnabled() {
 }
 /**
  * Log a debug message. Only outputs when --debug is enabled.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export function debug(module, message, ...args) {
     if (!debugEnabled)
@@ -24,6 +27,9 @@ export function debug(module, message, ...args) {
 /**
  * Log an informational message. Always outputs to stderr.
  * Use for user-facing progress indicators during long-running operations.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export function info(module, message, ...args) {
     const timestamp = new Date().toISOString();
@@ -31,6 +37,9 @@ export function info(module, message, ...args) {
 }
 /**
  * Log a warning. Always outputs.
+ * @param module - Module name for log prefix
+ * @param message - Warning message
+ * @param args - Additional values to log
  */
 export function warn(module, message, ...args) {
     const timestamp = new Date().toISOString();
@@ -38,6 +47,10 @@ export function warn(module, message, ...args) {
 }
 /**
  * Time an async operation and log duration in debug mode.
+ * @param module - Module name for log prefix
+ * @param label - Operation label for the timing log
+ * @param fn - Async function to time
+ * @returns The result of the async function
  */
 export async function timed(module, label, fn) {
     if (!debugEnabled)

package/dist/core/pr-monitor.d.ts

@@ -21,6 +21,9 @@ export { determineStatus } from './status-determination.js';
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.
+ *
+ * @param mergeable - GitHub's mergeable flag (null when not yet computed)
+ * @param mergeableState - GitHub's mergeable_state string
  */
 export declare function hasMergeConflict(mergeable: boolean | null, mergeableState: string | null): boolean;
 export interface PRCheckFailure {
@@ -31,13 +34,35 @@ export interface FetchPRsResult {
     prs: FetchedPR[];
     failures: PRCheckFailure[];
 }
+/**
+ * Fetches and enriches open PRs from GitHub for the configured user.
+ *
+ * In v2, all PR data is fetched fresh on each run — no local PR tracking.
+ * CI status, reviews, merge conflicts, and maintainer comments are enriched
+ * for each PR to compute a {@link FetchedPRStatus}.
+ */
 export declare class PRMonitor {
     private octokit;
     private stateManager;
+    /**
+     * @param githubToken - GitHub personal access token or token from `gh auth token`
+     */
     constructor(githubToken: string);
     /**
-     * Fetch all open PRs for the configured user fresh from GitHub
-     * This is the main entry point for the v2 architecture
+     * Fetch all open PRs for the configured user fresh from GitHub.
+     * This is the main entry point for the v2 architecture.
+     *
+     * @returns All open PRs enriched with status, plus any failures
+     * @throws {ConfigurationError} If no GitHub username is configured
+     *
+     * @example
+     * ```typescript
+     * import { PRMonitor, requireGitHubToken } from '@oss-autopilot/core';
+     *
+     * const monitor = new PRMonitor(requireGitHubToken());
+     * const { prs, failures } = await monitor.fetchUserOpenPRs();
+     * console.log(`Found ${prs.length} open PRs, ${failures.length} failures`);
+     * ```
      */
     fetchUserOpenPRs(): Promise<FetchPRsResult>;
     /**
@@ -51,7 +76,8 @@ export declare class PRMonitor {
     private buildFetchedPR;
     /**
      * Fetch merged PR counts and latest merge dates per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo merged counts with monthly breakdowns
      */
     fetchUserMergedPRCounts(starFilter?: StarFilter): Promise<PRCountsResult<{
         count: number;
@@ -59,7 +85,8 @@ export declare class PRMonitor {
     }>>;
     /**
      * Fetch closed-without-merge PR counts per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo closed counts with monthly breakdowns
      */
     fetchUserClosedPRCounts(starFilter?: StarFilter): Promise<PRCountsResult<number>>;
     /**
@@ -72,20 +99,28 @@ export declare class PRMonitor {
     }>>;
     /**
      * Fetch PRs closed without merge in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently closed PRs
      */
     fetchRecentlyClosedPRs(days?: number): Promise<ClosedPR[]>;
     /**
      * Fetch PRs merged in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently merged PRs
      */
     fetchRecentlyMergedPRs(days?: number): Promise<MergedPR[]>;
     /**
-     * Generate a daily digest from fetched PRs
+     * Generate a daily digest from fetched PRs.
+     * @param prs - All open PRs (active + shelved)
+     * @param recentlyClosedPRs - PRs closed without merge in the last 7 days
+     * @param recentlyMergedPRs - PRs merged in the last 7 days
+     * @returns Daily digest with categorized PRs and summary stats
      */
     generateDigest(prs: FetchedPR[], recentlyClosedPRs?: ClosedPR[], recentlyMergedPRs?: MergedPR[]): DailyDigest;
     /**
-     * Update repository scores based on observed PR (called when we detect merged/closed PRs)
+     * Update repository scores based on observed PR (called when we detect merged/closed PRs).
+     * @param repo - Repository in "owner/repo" format
+     * @param wasMerged - true if the PR was merged, false if closed without merge
      */
     updateRepoScoreFromObservedPR(repo: string, wasMerged: boolean): Promise<void>;
 }

package/dist/core/pr-monitor.js

@@ -35,22 +35,47 @@ export { determineStatus } from './status-determination.js';
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.
+ *
+ * @param mergeable - GitHub's mergeable flag (null when not yet computed)
+ * @param mergeableState - GitHub's mergeable_state string
  */
 export function hasMergeConflict(mergeable, mergeableState) {
     return mergeable === false || mergeableState === 'dirty';
 }
 const MODULE = 'pr-monitor';
 const MAX_CONCURRENT_REQUESTS = DEFAULT_CONCURRENCY;
+/**
+ * Fetches and enriches open PRs from GitHub for the configured user.
+ *
+ * In v2, all PR data is fetched fresh on each run — no local PR tracking.
+ * CI status, reviews, merge conflicts, and maintainer comments are enriched
+ * for each PR to compute a {@link FetchedPRStatus}.
+ */
 export class PRMonitor {
     octokit;
     stateManager;
+    /**
+     * @param githubToken - GitHub personal access token or token from `gh auth token`
+     */
     constructor(githubToken) {
         this.octokit = getOctokit(githubToken);
         this.stateManager = getStateManager();
     }
     /**
-     * Fetch all open PRs for the configured user fresh from GitHub
-     * This is the main entry point for the v2 architecture
+     * Fetch all open PRs for the configured user fresh from GitHub.
+     * This is the main entry point for the v2 architecture.
+     *
+     * @returns All open PRs enriched with status, plus any failures
+     * @throws {ConfigurationError} If no GitHub username is configured
+     *
+     * @example
+     * ```typescript
+     * import { PRMonitor, requireGitHubToken } from '@oss-autopilot/core';
+     *
+     * const monitor = new PRMonitor(requireGitHubToken());
+     * const { prs, failures } = await monitor.fetchUserOpenPRs();
+     * console.log(`Found ${prs.length} open PRs, ${failures.length} failures`);
+     * ```
      */
     async fetchUserOpenPRs() {
         const config = this.stateManager.getState().config;
@@ -287,7 +312,8 @@ export class PRMonitor {
     }
     /**
      * Fetch merged PR counts and latest merge dates per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo merged counts with monthly breakdowns
      */
     async fetchUserMergedPRCounts(starFilter) {
         const config = this.stateManager.getState().config;
@@ -295,7 +321,8 @@ export class PRMonitor {
     }
     /**
      * Fetch closed-without-merge PR counts per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo closed counts with monthly breakdowns
      */
     async fetchUserClosedPRCounts(starFilter) {
         const config = this.stateManager.getState().config;
@@ -357,7 +384,8 @@ export class PRMonitor {
     }
     /**
      * Fetch PRs closed without merge in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently closed PRs
      */
     async fetchRecentlyClosedPRs(days = 7) {
         const config = this.stateManager.getState().config;
@@ -365,14 +393,19 @@ export class PRMonitor {
     }
     /**
      * Fetch PRs merged in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently merged PRs
      */
     async fetchRecentlyMergedPRs(days = 7) {
         const config = this.stateManager.getState().config;
         return fetchRecentlyMergedPRsImpl(this.octokit, config, days);
     }
     /**
-     * Generate a daily digest from fetched PRs
+     * Generate a daily digest from fetched PRs.
+     * @param prs - All open PRs (active + shelved)
+     * @param recentlyClosedPRs - PRs closed without merge in the last 7 days
+     * @param recentlyMergedPRs - PRs merged in the last 7 days
+     * @returns Daily digest with categorized PRs and summary stats
      */
     generateDigest(prs, recentlyClosedPRs = [], recentlyMergedPRs = []) {
         const now = new Date().toISOString();
@@ -399,7 +432,9 @@ export class PRMonitor {
         };
     }
     /**
-     * Update repository scores based on observed PR (called when we detect merged/closed PRs)
+     * Update repository scores based on observed PR (called when we detect merged/closed PRs).
+     * @param repo - Repository in "owner/repo" format
+     * @param wasMerged - true if the PR was merged, false if closed without merge
      */
     async updateRepoScoreFromObservedPR(repo, wasMerged) {
         if (wasMerged) {

package/dist/core/state.d.ts

@@ -30,6 +30,7 @@ export declare class StateManager {
     /**
      * Execute multiple mutations as a single batch, deferring disk I/O until the
      * batch completes. Nested `batch()` calls are flattened — only the outermost saves.
+     * @param fn - The function containing mutations to batch
      */
     batch(fn: () => void): void;
     /**
@@ -63,51 +64,217 @@ export declare class StateManager {
      * Returns true if state was reloaded, false if unchanged or in-memory mode.
      */
     reloadIfChanged(): boolean;
+    /**
+     * Store the latest daily digest and update the digest timestamp.
+     * @param digest - The daily digest to store
+     */
     setLastDigest(digest: DailyDigest): void;
+    /**
+     * Update monthly merged PR counts for dashboard display.
+     * @param counts - Monthly merged PR counts keyed by YYYY-MM
+     */
     setMonthlyMergedCounts(counts: Record<string, number>): void;
+    /**
+     * Update monthly closed PR counts for dashboard display.
+     * @param counts - Monthly closed PR counts keyed by YYYY-MM
+     */
     setMonthlyClosedCounts(counts: Record<string, number>): void;
+    /**
+     * Update monthly opened PR counts for dashboard display.
+     * @param counts - Monthly opened PR counts keyed by YYYY-MM
+     */
     setMonthlyOpenedCounts(counts: Record<string, number>): void;
+    /**
+     * Update daily activity counts for dashboard display.
+     * @param counts - Daily activity counts keyed by YYYY-MM-DD
+     */
     setDailyActivityCounts(counts: Record<string, number>): void;
+    /**
+     * Update the local repository cache.
+     * @param cache - Local repository cache mapping repo names to paths
+     */
     setLocalRepoCache(cache: LocalRepoCache): void;
+    /** Returns all stored merged PRs (sorted by merge date descending via addMergedPRs). */
     getMergedPRs(): StoredMergedPR[];
+    /**
+     * Add merged PRs to storage, deduplicating by URL.
+     * @param prs - Merged PRs to add (duplicates by URL are ignored)
+     */
     addMergedPRs(prs: StoredMergedPR[]): void;
+    /** Returns the most recent merge date, used as a watermark for incremental fetching. */
     getMergedPRWatermark(): string | undefined;
+    /** Returns all stored closed-without-merge PRs (sorted by close date descending via addClosedPRs). */
     getClosedPRs(): StoredClosedPR[];
+    /**
+     * Add closed PRs to storage, deduplicating by URL.
+     * @param prs - Closed PRs to add (duplicates by URL are ignored)
+     */
     addClosedPRs(prs: StoredClosedPR[]): void;
+    /** Returns the most recent close date, used as a watermark for incremental fetching. */
     getClosedPRWatermark(): string | undefined;
+    /**
+     * Merge partial config updates into the current configuration.
+     * @param config - Partial config object to merge
+     */
     updateConfig(config: Partial<AgentState['config']>): void;
+    /**
+     * Append a new event to the event log and auto-persist.
+     * Events are capped at 1000 to prevent unbounded growth.
+     * @param type - The event type identifier
+     * @param data - Arbitrary event payload
+     */
     appendEvent(type: StateEventType, data: Record<string, unknown>): void;
+    /**
+     * Filter events by type.
+     * @param type - The event type to filter by
+     * @returns Events matching the given type
+     */
     getEventsByType(type: StateEventType): StateEvent[];
+    /**
+     * Filter events within a date range.
+     * @param since - Start of range (inclusive)
+     * @param until - End of range (inclusive), defaults to now
+     * @returns Events within the date range
+     */
     getEventsInRange(since: Date, until?: Date): StateEvent[];
+    /**
+     * Track a new issue. No-op if the issue URL is already tracked.
+     * @param issue - The issue to track
+     */
     addIssue(issue: TrackedIssue): void;
+    /**
+     * Add a repository to the trusted projects list. No-op if already trusted.
+     * @param repo - Repository in "owner/repo" format
+     */
     addTrustedProject(repo: string): void;
     private static matchesExclusion;
+    /**
+     * Remove excluded repos/orgs from trusted projects.
+     * @param repos - Repository names to exclude
+     * @param orgs - Organization names to exclude
+     */
     cleanupExcludedData(repos: string[], orgs: string[]): void;
+    /** Returns cached starred repository names. */
     getStarredRepos(): string[];
+    /**
+     * Update the cached starred repositories and timestamp.
+     * @param repos - Repository names in "owner/repo" format
+     */
     setStarredRepos(repos: string[]): void;
+    /** Returns true if starred repos cache is older than 24 hours. */
     isStarredReposStale(): boolean;
+    /**
+     * Shelve a PR URL, hiding it from daily digest and capacity.
+     * @param url - The PR URL to shelve
+     * @returns true if newly shelved, false if already shelved
+     */
     shelvePR(url: string): boolean;
+    /**
+     * Unshelve a PR URL, restoring it to daily digest.
+     * @param url - The PR URL to unshelve
+     * @returns true if removed from shelf, false if not shelved
+     */
     unshelvePR(url: string): boolean;
+    /**
+     * Check if a PR is currently shelved.
+     * @param url - The PR URL to check
+     * @returns true if the PR is shelved
+     */
     isPRShelved(url: string): boolean;
+    /**
+     * Dismiss an issue's notifications. Auto-resurfaces on new activity.
+     * @param url - The issue URL to dismiss
+     * @param timestamp - ISO timestamp of dismissal
+     * @returns true if newly dismissed, false if already dismissed
+     */
     dismissIssue(url: string, timestamp: string): boolean;
+    /**
+     * Restore a dismissed issue to notifications.
+     * @param url - The issue URL to undismiss
+     * @returns true if undismissed, false if not currently dismissed
+     */
     undismissIssue(url: string): boolean;
+    /**
+     * Get the timestamp when an issue was dismissed, or undefined if not dismissed.
+     * @param url - The issue URL to check
+     */
     getIssueDismissedAt(url: string): string | undefined;
+    /**
+     * Set a manual status override for a PR. Auto-clears when the PR has new activity.
+     * @param url - The PR URL
+     * @param status - The overridden status
+     * @param lastActivityAt - ISO timestamp of PR's last activity when override was set
+     */
     setStatusOverride(url: string, status: FetchedPRStatus, lastActivityAt: string): void;
+    /**
+     * Remove a manual status override for a PR.
+     * @param url - The PR URL
+     * @returns true if an override was removed, false if none existed
+     */
     clearStatusOverride(url: string): boolean;
+    /**
+     * Get the status override for a PR, auto-clearing if new activity has occurred.
+     * @param url - The PR URL
+     * @param currentUpdatedAt - PR's current updatedAt timestamp for staleness check
+     * @returns The override if still valid, undefined otherwise
+     */
     getStatusOverride(url: string, currentUpdatedAt?: string): StatusOverride | undefined;
+    /**
+     * Get the score record for a repository.
+     * @param repo - Repository in "owner/repo" format
+     * @returns Read-only score record, or undefined if not tracked
+     */
     getRepoScore(repo: string): Readonly<RepoScore> | undefined;
+    /**
+     * Update scoring data for a repository.
+     * @param repo - Repository in "owner/repo" format
+     * @param updates - Partial score fields to merge
+     */
     updateRepoScore(repo: string, updates: RepoScoreUpdate): void;
+    /**
+     * Increment the merged PR count for a repository.
+     * @param repo - Repository in "owner/repo" format
+     */
     incrementMergedCount(repo: string): void;
+    /**
+     * Increment the closed-without-merge PR count.
+     * @param repo - Repository in "owner/repo" format
+     */
     incrementClosedCount(repo: string): void;
+    /**
+     * Mark a repository as hostile (score zeroed).
+     * @param repo - Repository in "owner/repo" format
+     */
     markRepoHostile(repo: string): void;
+    /** Returns repository names that have at least one merged PR. */
     getReposWithMergedPRs(): string[];
+    /** Returns repository names with open PRs but no merged PRs yet. */
     getReposWithOpenPRs(): string[];
+    /**
+     * Returns repos above the score threshold.
+     * @param minScore - Minimum score (default: config.minRepoScoreThreshold)
+     */
     getHighScoringRepos(minScore?: number): string[];
+    /**
+     * Returns repos below the score threshold.
+     * @param maxScore - Maximum score (default: config.minRepoScoreThreshold)
+     */
     getLowScoringRepos(maxScore?: number): string[];
+    /** Returns aggregate contribution statistics (merge rate, PR counts, repo breakdown). */
     getStats(): Stats;
 }
 /**
  * Get the singleton StateManager instance, creating it on first call.
+ * @returns The shared StateManager instance
+ *
+ * @example
+ * ```typescript
+ * import { getStateManager } from '@oss-autopilot/core';
+ *
+ * const state = getStateManager();
+ * const config = state.getState().config;
+ * console.log(config.githubUsername);
+ * ```
  */
 export declare function getStateManager(): StateManager;
 /**