@oss-autopilot/core 0.51.0 → 0.52.0

package/dist/core/state.d.ts

@@ -1,36 +1,23 @@
 /**
- * State management for the OSS Contribution Agent
- * Persists state to a JSON file in ~/.oss-autopilot/
+ * State management for the OSS Contribution Agent.
+ * Thin coordinator that delegates persistence to state-persistence.ts
+ * and scoring logic to repo-score-manager.ts.
  */
 import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, StatusOverride, FetchedPRStatus, StoredMergedPR, StoredClosedPR } 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;
+import type { Stats } from './repo-score-manager.js';
+export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
+export type { Stats } from './repo-score-manager.js';
 /**
  * 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.
+ * Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts.
+ * Retains lightweight CRUD operations for config, events, issues, shelving, dismissal,
+ * and status overrides.
  */
 export declare class StateManager {
     private state;
     private readonly inMemoryOnly;
+    private lastLoadedMtimeMs;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -38,13 +25,8 @@ export declare class StateManager {
      *   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;
     /**
@@ -53,343 +35,71 @@ export declare class StateManager {
     markSetupComplete(): void;
     /**
      * Initialize state with sensible defaults for zero-config onboarding.
-     * Sets the GitHub username, marks setup as complete, and persists.
-     * No-op if setup is already complete (prevents overwriting existing config).
-     * @param username - The GitHub username to configure.
+     * No-op if setup is already complete.
      */
     initializeWithDefaults(username: string): 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.
+     * state file first. In in-memory mode, only updates `lastRunAt` without any file I/O.
      */
     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.
+     * Re-read state from disk if the file has been modified since the last load/save.
+     * Returns true if state was reloaded, false if unchanged or in-memory mode.
      */
+    reloadIfChanged(): boolean;
     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;
-    /**
-     * Get all stored merged PRs.
-     * @returns Array of stored merged PRs, sorted by mergedAt desc.
-     */
+    setLocalRepoCache(cache: LocalRepoCache): void;
     getMergedPRs(): StoredMergedPR[];
-    /**
-     * Add new merged PRs to the stored list. Deduplicates by URL and sorts by mergedAt desc.
-     * @param prs - New merged PRs to add.
-     */
     addMergedPRs(prs: StoredMergedPR[]): void;
-    /**
-     * Get the most recent mergedAt timestamp from stored merged PRs.
-     * Used as the watermark for incremental fetching.
-     * @returns ISO date string of the most recent merge, or undefined if no stored PRs.
-     */
     getMergedPRWatermark(): string | undefined;
-    /**
-     * Get all stored closed PRs.
-     * @returns Array of stored closed PRs, sorted by closedAt desc.
-     */
     getClosedPRs(): StoredClosedPR[];
-    /**
-     * Add new closed PRs to the stored list. Deduplicates by URL and sorts by closedAt desc.
-     * @param prs - New closed PRs to add.
-     */
     addClosedPRs(prs: StoredClosedPR[]): void;
-    /**
-     * Get the most recent closedAt timestamp from stored closed PRs.
-     * Used as the watermark for incremental fetching.
-     * @returns ISO date string of the most recent close, or undefined if no stored PRs.
-     */
     getClosedPRWatermark(): string | undefined;
-    /**
-     * 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;
-    /**
-     * Remove repositories matching the given exclusion lists from `trustedProjects`.
-     * Called when a repo or org is newly excluded.
-     *
-     * Note: `repoScores` are intentionally preserved so historical stats (merge rate,
-     * total merged) remain accurate. Exclusion only affects issue discovery (#591).
-     * @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;
-    /**
-     * Set a manual status override for a PR.
-     * @param url - The full GitHub PR URL.
-     * @param status - The target status to override to.
-     * @param lastActivityAt - The PR's current updatedAt timestamp (for auto-clear detection).
-     */
     setStatusOverride(url: string, status: FetchedPRStatus, lastActivityAt: string): void;
-    /**
-     * Clear a status override for a PR.
-     * @param url - The full GitHub PR URL.
-     * @returns true if found and removed, false if no override existed.
-     */
     clearStatusOverride(url: string): boolean;
-    /**
-     * Get the status override for a PR, if one exists and hasn't been auto-cleared.
-     * @param url - The full GitHub PR URL.
-     * @param currentUpdatedAt - The PR's current updatedAt from GitHub. If newer than
-     *   the stored lastActivityAt, the override is stale and auto-cleared.
-     * @returns The override metadata, or undefined if none exists or it was auto-cleared.
-     */
     getStatusOverride(url: string, currentUpdatedAt?: string): StatusOverride | undefined;
-    /**
-     * 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.
-     */
+    getRepoScore(repo: string): Readonly<RepoScore> | undefined;
     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. `totalTracked` reflects the number of repositories with
-     * score records above the minStars threshold.
-     *
-     * Note: `excludeRepos`/`excludeOrgs` only affect issue discovery, not stats (#591).
-     * @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 (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;
-}
 /**
  * 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.
+ * Reset the singleton StateManager instance to null. Intended for test isolation.
  */
 export declare function resetStateManager(): void;