@oss-autopilot/core 0.58.0 → 0.60.0

package/dist/core/state-schema.js

@@ -0,0 +1,214 @@
+/**
+ * Zod schemas for all types persisted in state.json.
+ *
+ * This file is the single source of truth for persisted type shapes.
+ * Types are inferred via `z.infer<>` at the bottom of this file and
+ * re-exported through types.ts.
+ *
+ * Schemas are defined bottom-up (leaf types first, composites last).
+ * Unknown keys are stripped by default (Zod 4 behavior).
+ */
+import { z } from 'zod';
+// ── 1. Enum / union schemas ───────────────────────────────────────────
+export const IssueStatusSchema = z.enum(['candidate', 'claimed', 'in_progress', 'pr_submitted']);
+export const FetchedPRStatusSchema = z.enum(['needs_addressing', 'waiting_on_maintainer']);
+export const ProjectCategorySchema = z.enum([
+    'nonprofit',
+    'devtools',
+    'infrastructure',
+    'web-frameworks',
+    'data-ml',
+    'education',
+]);
+export const IssueScopeSchema = z.enum(['beginner', 'intermediate', 'advanced']);
+export const StateEventTypeSchema = z.enum([
+    'pr_tracked',
+    'pr_merged',
+    'pr_closed',
+    'pr_dormant',
+    'daily_check',
+    'comment_posted',
+]);
+// ── 2. Leaf schemas ──────────────────────────────────────────────────
+export const RepoSignalsSchema = z.object({
+    hasActiveMaintainers: z.boolean(),
+    isResponsive: z.boolean(),
+    hasHostileComments: z.boolean(),
+});
+export const RepoScoreSchema = z.object({
+    repo: z.string(),
+    score: z.number(),
+    mergedPRCount: z.number(),
+    closedWithoutMergeCount: z.number(),
+    avgResponseDays: z.number().nullable(),
+    lastMergedAt: z.string().optional(),
+    lastEvaluatedAt: z.string(),
+    signals: RepoSignalsSchema,
+    stargazersCount: z.number().optional(),
+    language: z.string().nullable().optional(),
+});
+export const StateEventSchema = z.object({
+    id: z.string(),
+    type: StateEventTypeSchema,
+    at: z.string(),
+    data: z.record(z.string(), z.unknown()),
+});
+export const StoredMergedPRSchema = z.object({
+    url: z.string(),
+    title: z.string(),
+    mergedAt: z.string(),
+});
+export const StoredClosedPRSchema = z.object({
+    url: z.string(),
+    title: z.string(),
+    closedAt: z.string(),
+});
+// ── 3. Contribution schemas ──────────────────────────────────────────
+export const ContributionGuidelinesSchema = z.object({
+    branchNamingConvention: z.string().optional(),
+    commitMessageFormat: z.string().optional(),
+    prTitleFormat: z.string().optional(),
+    requiredChecks: z.array(z.string()).optional(),
+    testFramework: z.string().optional(),
+    testCoverageRequired: z.boolean().optional(),
+    testFileNaming: z.string().optional(),
+    linter: z.string().optional(),
+    formatter: z.string().optional(),
+    styleGuideUrl: z.string().optional(),
+    issueClaimProcess: z.string().optional(),
+    reviewProcess: z.string().optional(),
+    claRequired: z.boolean().optional(),
+    rawContent: z.string().optional(),
+});
+export const IssueVettingResultSchema = z.object({
+    passedAllChecks: z.boolean(),
+    checks: z.object({
+        noExistingPR: z.boolean(),
+        notClaimed: z.boolean(),
+        projectActive: z.boolean(),
+        clearRequirements: z.boolean(),
+        contributionGuidelinesFound: z.boolean(),
+    }),
+    contributionGuidelines: ContributionGuidelinesSchema.optional(),
+    notes: z.array(z.string()),
+});
+export const TrackedIssueSchema = z.object({
+    id: z.number(),
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    status: IssueStatusSchema,
+    labels: z.array(z.string()),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    vetted: z.boolean(),
+    vettingResult: IssueVettingResultSchema.optional(),
+});
+// ── 4. PR reference schemas ──────────────────────────────────────────
+export const ShelvedPRRefSchema = z.object({
+    number: z.number(),
+    url: z.string(),
+    title: z.string(),
+    repo: z.string(),
+    daysSinceActivity: z.number(),
+    status: FetchedPRStatusSchema,
+});
+export const StatusOverrideSchema = z.object({
+    status: FetchedPRStatusSchema,
+    setAt: z.string(),
+    lastActivityAt: z.string(),
+});
+// ── 5. Config schema ─────────────────────────────────────────────────
+export const AgentConfigSchema = z.object({
+    setupComplete: z.boolean().default(false),
+    setupCompletedAt: z.string().optional(),
+    maxActivePRs: z.number().default(10),
+    dormantThresholdDays: z.number().default(30),
+    approachingDormantDays: z.number().default(25),
+    maxIssueAgeDays: z.number().default(90),
+    languages: z.array(z.string()).default(['typescript', 'javascript']),
+    labels: z.array(z.string()).default(['good first issue', 'help wanted']),
+    scope: z.array(IssueScopeSchema).optional(),
+    excludeRepos: z.array(z.string()).default([]),
+    excludeOrgs: z.array(z.string()).optional(),
+    trustedProjects: z.array(z.string()).default([]),
+    githubUsername: z.string().default(''),
+    minRepoScoreThreshold: z.number().default(4),
+    starredRepos: z.array(z.string()).default([]),
+    starredReposLastFetched: z.string().optional(),
+    showHealthCheck: z.boolean().optional(),
+    squashByDefault: z.union([z.boolean(), z.literal('ask')]).default(true),
+    localRepoScanPaths: z.array(z.string()).optional(),
+    minStars: z.number().default(50),
+    includeDocIssues: z.boolean().default(true),
+    aiPolicyBlocklist: z.array(z.string()).default(['matplotlib/matplotlib']),
+    shelvedPRUrls: z.array(z.string()).default([]),
+    dismissedIssues: z.record(z.string(), z.string()).default({}),
+    statusOverrides: z.record(z.string(), StatusOverrideSchema).optional(),
+    issueListPath: z.string().optional(),
+    projectCategories: z.array(ProjectCategorySchema).default([]),
+    preferredOrgs: z.array(z.string()).default([]),
+});
+// ── 6. Cache schemas ─────────────────────────────────────────────────
+export const LocalRepoCacheSchema = z.object({
+    repos: z.record(z.string(), z.object({
+        path: z.string(),
+        exists: z.boolean(),
+        currentBranch: z.string().nullable(),
+    })),
+    scanPaths: z.array(z.string()),
+    cachedAt: z.string(),
+});
+// ── 7. Digest schemas ────────────────────────────────────────────────
+export const ClosedPRSchema = z.object({
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    closedAt: z.string(),
+    closedBy: z.string().optional(),
+});
+export const MergedPRSchema = z.object({
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    mergedAt: z.string(),
+});
+export const DailyDigestSummarySchema = z.object({
+    totalActivePRs: z.number(),
+    totalNeedingAttention: z.number(),
+    totalMergedAllTime: z.number(),
+    mergeRate: z.number(),
+});
+export const DailyDigestSchema = z.object({
+    generatedAt: z.string(),
+    // FetchedPR arrays — ephemeral, regenerated each run. Validated loosely.
+    openPRs: z.array(z.any()),
+    needsAddressingPRs: z.array(z.any()),
+    waitingOnMaintainerPRs: z.array(z.any()),
+    recentlyClosedPRs: z.array(ClosedPRSchema),
+    recentlyMergedPRs: z.array(MergedPRSchema),
+    shelvedPRs: z.array(ShelvedPRRefSchema),
+    autoUnshelvedPRs: z.array(ShelvedPRRefSchema),
+    summary: DailyDigestSummarySchema,
+});
+// ── 8. Root schema ───────────────────────────────────────────────────
+export const AgentStateSchema = z.object({
+    version: z.literal(2),
+    repoScores: z.record(z.string(), RepoScoreSchema).default({}),
+    config: AgentConfigSchema.default(() => AgentConfigSchema.parse({})),
+    events: z.array(StateEventSchema).default([]),
+    lastRunAt: z.string().default(() => new Date().toISOString()),
+    lastDigestAt: z.string().optional(),
+    lastDigest: DailyDigestSchema.optional(),
+    monthlyMergedCounts: z.record(z.string(), z.number()).optional(),
+    monthlyClosedCounts: z.record(z.string(), z.number()).optional(),
+    monthlyOpenedCounts: z.record(z.string(), z.number()).optional(),
+    dailyActivityCounts: z.record(z.string(), z.number()).optional(),
+    localRepoCache: LocalRepoCacheSchema.optional(),
+    mergedPRs: z.array(StoredMergedPRSchema).optional(),
+    closedPRs: z.array(StoredClosedPRSchema).optional(),
+    activeIssues: z.array(TrackedIssueSchema).default([]),
+});

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;
 /**