@oss-autopilot/core 0.58.0 → 0.59.0

package/dist/core/state.js

@@ -43,6 +43,7 @@ export 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) {
         if (this._batching) {
@@ -132,35 +133,64 @@ export class StateManager {
         return true;
     }
     // === Dashboard Data Setters ===
+    /**
+     * Store the latest daily digest and update the digest timestamp.
+     * @param digest - The daily digest to store
+     */
     setLastDigest(digest) {
         this.state.lastDigest = digest;
         this.state.lastDigestAt = digest.generatedAt;
         this.autoSave();
     }
+    /**
+     * Update monthly merged PR counts for dashboard display.
+     * @param counts - Monthly merged PR counts keyed by YYYY-MM
+     */
     setMonthlyMergedCounts(counts) {
         this.state.monthlyMergedCounts = counts;
         this.autoSave();
     }
+    /**
+     * Update monthly closed PR counts for dashboard display.
+     * @param counts - Monthly closed PR counts keyed by YYYY-MM
+     */
     setMonthlyClosedCounts(counts) {
         this.state.monthlyClosedCounts = counts;
         this.autoSave();
     }
+    /**
+     * Update monthly opened PR counts for dashboard display.
+     * @param counts - Monthly opened PR counts keyed by YYYY-MM
+     */
     setMonthlyOpenedCounts(counts) {
         this.state.monthlyOpenedCounts = counts;
         this.autoSave();
     }
+    /**
+     * Update daily activity counts for dashboard display.
+     * @param counts - Daily activity counts keyed by YYYY-MM-DD
+     */
     setDailyActivityCounts(counts) {
         this.state.dailyActivityCounts = counts;
         this.autoSave();
     }
+    /**
+     * Update the local repository cache.
+     * @param cache - Local repository cache mapping repo names to paths
+     */
     setLocalRepoCache(cache) {
         this.state.localRepoCache = cache;
         this.autoSave();
     }
     // === Merged PR Storage ===
+    /** Returns all stored merged PRs (sorted by merge date descending via addMergedPRs). */
     getMergedPRs() {
         return this.state.mergedPRs ?? [];
     }
+    /**
+     * Add merged PRs to storage, deduplicating by URL.
+     * @param prs - Merged PRs to add (duplicates by URL are ignored)
+     */
     addMergedPRs(prs) {
         if (prs.length === 0)
             return;
@@ -175,13 +205,19 @@ export class StateManager {
         debug(MODULE, `Added ${newPRs.length} merged PRs (total: ${this.state.mergedPRs.length})`);
         this.autoSave();
     }
+    /** Returns the most recent merge date, used as a watermark for incremental fetching. */
     getMergedPRWatermark() {
         return this.state.mergedPRs?.[0]?.mergedAt || undefined;
     }
     // === Closed PR Storage ===
+    /** Returns all stored closed-without-merge PRs (sorted by close date descending via addClosedPRs). */
     getClosedPRs() {
         return this.state.closedPRs ?? [];
     }
+    /**
+     * Add closed PRs to storage, deduplicating by URL.
+     * @param prs - Closed PRs to add (duplicates by URL are ignored)
+     */
     addClosedPRs(prs) {
         if (prs.length === 0)
             return;
@@ -196,15 +232,26 @@ export class StateManager {
         debug(MODULE, `Added ${newPRs.length} closed PRs (total: ${this.state.closedPRs.length})`);
         this.autoSave();
     }
+    /** Returns the most recent close date, used as a watermark for incremental fetching. */
     getClosedPRWatermark() {
         return this.state.closedPRs?.[0]?.closedAt || undefined;
     }
     // === Configuration ===
+    /**
+     * Merge partial config updates into the current configuration.
+     * @param config - Partial config object to merge
+     */
     updateConfig(config) {
         this.state.config = { ...this.state.config, ...config };
         this.autoSave();
     }
     // === Event Logging ===
+    /**
+     * 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, data) {
         const event = {
             id: `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
@@ -219,9 +266,20 @@ export class StateManager {
         }
         this.autoSave();
     }
+    /**
+     * Filter events by type.
+     * @param type - The event type to filter by
+     * @returns Events matching the given type
+     */
     getEventsByType(type) {
         return this.state.events.filter((e) => e.type === type);
     }
+    /**
+     * 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, until = new Date()) {
         return this.state.events.filter((e) => {
             const eventTime = new Date(e.at);
@@ -229,6 +287,10 @@ export class StateManager {
         });
     }
     // === Issue Management ===
+    /**
+     * Track a new issue. No-op if the issue URL is already tracked.
+     * @param issue - The issue to track
+     */
     addIssue(issue) {
         const existing = this.state.activeIssues.find((i) => i.url === issue.url);
         if (existing) {
@@ -240,6 +302,10 @@ export class StateManager {
         this.autoSave();
     }
     // === Trusted Projects ===
+    /**
+     * Add a repository to the trusted projects list. No-op if already trusted.
+     * @param repo - Repository in "owner/repo" format
+     */
     addTrustedProject(repo) {
         if (!this.state.config.trustedProjects.includes(repo)) {
             this.state.config.trustedProjects.push(repo);
@@ -255,6 +321,11 @@ export class StateManager {
             return true;
         return false;
     }
+    /**
+     * Remove excluded repos/orgs from trusted projects.
+     * @param repos - Repository names to exclude
+     * @param orgs - Organization names to exclude
+     */
     cleanupExcludedData(repos, orgs) {
         const matches = (repo) => StateManager.matchesExclusion(repo, repos, orgs);
         const beforeTrusted = this.state.config.trustedProjects.length;
@@ -266,15 +337,21 @@ export class StateManager {
         }
     }
     // === Starred Repos Management ===
+    /** Returns cached starred repository names. */
     getStarredRepos() {
         return this.state.config.starredRepos || [];
     }
+    /**
+     * Update the cached starred repositories and timestamp.
+     * @param repos - Repository names in "owner/repo" format
+     */
     setStarredRepos(repos) {
         this.state.config.starredRepos = repos;
         this.state.config.starredReposLastFetched = new Date().toISOString();
         debug(MODULE, `Updated starred repos: ${repos.length} repositories`);
         this.autoSave();
     }
+    /** Returns true if starred repos cache is older than 24 hours. */
     isStarredReposStale() {
         const lastFetched = this.state.config.starredReposLastFetched;
         if (!lastFetched) {
@@ -286,6 +363,11 @@ export class StateManager {
         return now.getTime() - lastFetchedDate.getTime() > staleThresholdMs;
     }
     // === Shelve/Unshelve ===
+    /**
+     * 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) {
         if (!this.state.config.shelvedPRUrls) {
             this.state.config.shelvedPRUrls = [];
@@ -297,6 +379,11 @@ export class StateManager {
         this.autoSave();
         return true;
     }
+    /**
+     * 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) {
         if (!this.state.config.shelvedPRUrls) {
             return false;
@@ -309,10 +396,21 @@ export class StateManager {
         this.autoSave();
         return true;
     }
+    /**
+     * Check if a PR is currently shelved.
+     * @param url - The PR URL to check
+     * @returns true if the PR is shelved
+     */
     isPRShelved(url) {
         return this.state.config.shelvedPRUrls?.includes(url) ?? false;
     }
     // === Dismiss / Undismiss Issues ===
+    /**
+     * 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, timestamp) {
         if (!this.state.config.dismissedIssues) {
             this.state.config.dismissedIssues = {};
@@ -324,6 +422,11 @@ export class StateManager {
         this.autoSave();
         return true;
     }
+    /**
+     * Restore a dismissed issue to notifications.
+     * @param url - The issue URL to undismiss
+     * @returns true if undismissed, false if not currently dismissed
+     */
     undismissIssue(url) {
         if (!this.state.config.dismissedIssues || !(url in this.state.config.dismissedIssues)) {
             return false;
@@ -332,10 +435,20 @@ export class StateManager {
         this.autoSave();
         return true;
     }
+    /**
+     * Get the timestamp when an issue was dismissed, or undefined if not dismissed.
+     * @param url - The issue URL to check
+     */
     getIssueDismissedAt(url) {
         return this.state.config.dismissedIssues?.[url];
     }
     // === Status Overrides ===
+    /**
+     * 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, status, lastActivityAt) {
         if (!this.state.config.statusOverrides) {
             this.state.config.statusOverrides = {};
@@ -347,6 +460,11 @@ export class StateManager {
         };
         this.autoSave();
     }
+    /**
+     * 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) {
         if (!this.state.config.statusOverrides || !(url in this.state.config.statusOverrides)) {
             return false;
@@ -355,6 +473,12 @@ export class StateManager {
         this.autoSave();
         return true;
     }
+    /**
+     * 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, currentUpdatedAt) {
         const override = this.state.config.statusOverrides?.[url];
         if (!override)
@@ -367,37 +491,70 @@ export class StateManager {
         return override;
     }
     // === Repository Scoring (delegated to repo-score-manager) ===
+    /**
+     * 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) {
         return repoScoring.getRepoScore(this.state, repo);
     }
+    /**
+     * Update scoring data for a repository.
+     * @param repo - Repository in "owner/repo" format
+     * @param updates - Partial score fields to merge
+     */
     updateRepoScore(repo, updates) {
         repoScoring.updateRepoScore(this.state, repo, updates);
         this.autoSave();
     }
+    /**
+     * Increment the merged PR count for a repository.
+     * @param repo - Repository in "owner/repo" format
+     */
     incrementMergedCount(repo) {
         repoScoring.incrementMergedCount(this.state, repo);
         this.autoSave();
     }
+    /**
+     * Increment the closed-without-merge PR count.
+     * @param repo - Repository in "owner/repo" format
+     */
     incrementClosedCount(repo) {
         repoScoring.incrementClosedCount(this.state, repo);
         this.autoSave();
     }
+    /**
+     * Mark a repository as hostile (score zeroed).
+     * @param repo - Repository in "owner/repo" format
+     */
     markRepoHostile(repo) {
         repoScoring.markRepoHostile(this.state, repo);
         this.autoSave();
     }
+    /** Returns repository names that have at least one merged PR. */
     getReposWithMergedPRs() {
         return repoScoring.getReposWithMergedPRs(this.state);
     }
+    /** Returns repository names with open PRs but no merged PRs yet. */
     getReposWithOpenPRs() {
         return repoScoring.getReposWithOpenPRs(this.state);
     }
+    /**
+     * Returns repos above the score threshold.
+     * @param minScore - Minimum score (default: config.minRepoScoreThreshold)
+     */
     getHighScoringRepos(minScore) {
         return repoScoring.getHighScoringRepos(this.state, minScore);
     }
+    /**
+     * Returns repos below the score threshold.
+     * @param maxScore - Maximum score (default: config.minRepoScoreThreshold)
+     */
     getLowScoringRepos(maxScore) {
         return repoScoring.getLowScoringRepos(this.state, maxScore);
     }
+    /** Returns aggregate contribution statistics (merge rate, PR counts, repo breakdown). */
     getStats() {
         return repoScoring.getStats(this.state);
     }
@@ -406,6 +563,16 @@ export class StateManager {
 let stateManager = null;
 /**
  * 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 function getStateManager() {
     if (!stateManager) {

package/dist/core/types.d.ts

@@ -162,15 +162,9 @@ export interface FetchedPR {
  * Lightweight reference used in {@link DailyDigest} for shelved and auto-unshelved PRs.
  * Contains only the fields needed for display, avoiding duplication of the full
  * {@link FetchedPR} objects already present in `openPRs` and the status-specific arrays.
+ * Derived from {@link FetchedPR} via `Pick<>` to stay in sync automatically.
  */
-export interface ShelvedPRRef {
-    number: number;
-    url: string;
-    title: string;
-    repo: string;
-    daysSinceActivity: number;
-    status: FetchedPRStatus;
-}
+export type ShelvedPRRef = Pick<FetchedPR, 'number' | 'url' | 'title' | 'repo' | 'daysSinceActivity' | 'status'>;
 /** An issue tracked through the contribution pipeline from discovery to PR submission. */
 export interface TrackedIssue {
     id: number;

package/dist/formatters/json.d.ts

@@ -6,6 +6,7 @@ import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, She
 import type { ContributionStats } from '../core/stats.js';
 import type { PRCheckFailure } from '../core/pr-monitor.js';
 import type { SearchPriority } from '../core/types.js';
+import type { CIFormatterDiagnosis, FormatterDetectionResult } from '../core/formatter-detection.js';
 export interface JsonOutput<T = unknown> {
     success: boolean;
     data?: T;
@@ -304,6 +305,10 @@ export interface LocalReposOutput {
     cachedAt: string;
     fromCache: boolean;
 }
+/** Output of the detect-formatters command. Extends FormatterDetectionResult with optional CI diagnosis. */
+export interface DetectFormattersOutput extends FormatterDetectionResult {
+    ciDiagnosis?: CIFormatterDiagnosis;
+}
 /** Output of the stats command */
 export interface StatsOutput extends ContributionStats {
     mergeRateFormatted: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -53,10 +53,11 @@
     "commander": "^14.0.3"
   },
   "devDependencies": {
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.4.0",
     "@vitest/coverage-v8": "^4.0.18",
     "esbuild": "^0.27.3",
     "tsx": "^4.21.0",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
   },
@@ -68,6 +69,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "docs": "typedoc",
+    "docs:check": "typedoc --emit none"
   }
 }