@oss-autopilot/core 0.58.0 → 0.60.0

package/dist/core/types.d.ts

@@ -1,14 +1,8 @@
 /**
  * Core types for the Open Source Contribution Agent
  */
-/**
- * Lifecycle of a discovered issue through the contribution pipeline.
- * - `candidate` — Discovered but not yet claimed
- * - `claimed` — Contributor has claimed the issue (e.g., commented "I'll work on this")
- * - `in_progress` — Work is underway locally
- * - `pr_submitted` — A PR has been opened for this issue
- */
-export type IssueStatus = 'candidate' | 'claimed' | 'in_progress' | 'pr_submitted';
+import type { FetchedPRStatus, RepoSignals, TrackedIssue, IssueVettingResult, IssueScope, AgentConfig, AgentState } from './state-schema.js';
+export type { IssueStatus, FetchedPRStatus, ProjectCategory, IssueScope, StateEventType, RepoSignals, RepoScore, StateEvent, StoredMergedPR, StoredClosedPR, ContributionGuidelines, IssueVettingResult, TrackedIssue, ShelvedPRRef, StatusOverride, AgentConfig, LocalRepoCache, ClosedPR, MergedPR, DailyDigest, AgentState, } from './state-schema.js';
 /** CI pipeline status for a PR's latest commit. */
 export type CIStatus = 'passing' | 'failing' | 'pending' | 'unknown';
 /**
@@ -82,14 +76,6 @@ export type ActionReason = 'needs_response' | 'needs_changes' | 'failing_ci' | '
 export type WaitReason = 'pending_review' | 'pending_merge' | 'changes_addressed' | 'ci_blocked' | 'stale_ci_failure';
 /** How stale is the PR based on days since activity. Orthogonal to status. */
 export type StalenessTier = 'active' | 'approaching_dormant' | 'dormant';
-/**
- * Top-level classification of a PR's state. Only two values:
- * - `needs_addressing` — Contributor's turn. See `actionReason` for what to do.
- * - `waiting_on_maintainer` — Maintainer's turn. See `waitReason` for why.
- *
- * Staleness (active/approaching_dormant/dormant) is tracked separately in `stalenessTier`.
- */
-export type FetchedPRStatus = 'needs_addressing' | 'waiting_on_maintainer';
 /**
  * Hints about what a maintainer is asking for in their review comments.
  * Extracted from comment text by keyword matching.
@@ -158,74 +144,6 @@ export interface FetchedPR {
     /** Hints extracted from maintainer comments about what actions they are requesting. */
     maintainerActionHints: MaintainerActionHint[];
 }
-/**
- * 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.
- */
-export interface ShelvedPRRef {
-    number: number;
-    url: string;
-    title: string;
-    repo: string;
-    daysSinceActivity: number;
-    status: FetchedPRStatus;
-}
-/** An issue tracked through the contribution pipeline from discovery to PR submission. */
-export interface TrackedIssue {
-    id: number;
-    url: string;
-    repo: string;
-    number: number;
-    title: string;
-    status: IssueStatus;
-    labels: string[];
-    createdAt: string;
-    updatedAt: string;
-    /** Whether the issue has been through the vetting process (checking for existing PRs, activity, etc.). */
-    vetted: boolean;
-    vettingResult?: IssueVettingResult;
-}
-/**
- * Result of vetting an issue for contribution suitability.
- * An issue passes vetting when all checks are true (no existing PR, not claimed, etc.).
- */
-export interface IssueVettingResult {
-    passedAllChecks: boolean;
-    checks: {
-        noExistingPR: boolean;
-        notClaimed: boolean;
-        projectActive: boolean;
-        clearRequirements: boolean;
-        contributionGuidelinesFound: boolean;
-    };
-    contributionGuidelines?: ContributionGuidelines;
-    /** Free-text observations from the vetting process (e.g., "Issue has 3 linked PRs, all closed"). */
-    notes: string[];
-}
-/**
- * Structured representation of a project's contribution guidelines,
- * extracted from CONTRIBUTING.md or similar files during issue vetting.
- */
-export interface ContributionGuidelines {
-    branchNamingConvention?: string;
-    commitMessageFormat?: string;
-    prTitleFormat?: string;
-    requiredChecks?: string[];
-    testFramework?: string;
-    testCoverageRequired?: boolean;
-    /** Expected test file naming pattern (e.g., `"*.test.ts"`, `"*_spec.rb"`). */
-    testFileNaming?: string;
-    linter?: string;
-    formatter?: string;
-    styleGuideUrl?: string;
-    /** How to claim an issue (e.g., "Comment on the issue before starting work"). */
-    issueClaimProcess?: string;
-    reviewProcess?: string;
-    claRequired?: boolean;
-    /** Raw CONTRIBUTING.md content for reference when structured fields are insufficient. */
-    rawContent?: string;
-}
 /** Health snapshot of a GitHub repository, used to determine if a project is worth contributing to. */
 export interface ProjectHealth {
     repo: string;
@@ -245,38 +163,6 @@ export interface ProjectHealth {
     checkFailed?: boolean;
     failureReason?: string;
 }
-/**
- * Quality score for a repository, used to prioritize issue search results.
- * Score is on a 1-10 scale: base 5, logarithmic merge bonus (max +5: 1->+2, 2->+3, 3->+4, 5+->+5),
- * -1 per closed-without-merge (max -3), +1 if lastMergedAt is set and within 90 days,
- * +1 if responsive, -2 if hostile.
- * Repos below `AgentConfig.minRepoScoreThreshold` are deprioritized.
- */
-export interface RepoScore {
-    repo: string;
-    /** Overall score from 1 (avoid) to 10 (excellent track record). */
-    score: number;
-    /** Number of the contributor's PRs that were merged in this repo. */
-    mergedPRCount: number;
-    /** Number of the contributor's PRs closed without merge (indicates friction). */
-    closedWithoutMergeCount: number;
-    /** Average days for maintainers to respond; null if no data. */
-    avgResponseDays: number | null;
-    lastMergedAt?: string;
-    lastEvaluatedAt: string;
-    /** Qualitative signals about the repo's maintainer culture. */
-    signals: RepoSignals;
-    /** GitHub star count, fetched during daily check for dashboard filtering. */
-    stargazersCount?: number;
-    /** Primary programming language of the repo, fetched during daily check. */
-    language?: string | null;
-}
-/** Full set of qualitative signals about a repo's maintainer culture. */
-export interface RepoSignals {
-    hasActiveMaintainers: boolean;
-    isResponsive: boolean;
-    hasHostileComments: boolean;
-}
 /** Signals computed from observed open PR data, suitable for merging into RepoScore.signals. */
 export type ComputedRepoSignals = Pick<RepoSignals, 'isResponsive' | 'hasActiveMaintainers'>;
 /**
@@ -300,141 +186,6 @@ export interface RepoMetadataEntry {
     stars?: number;
     language?: string | null;
 }
-/**
- * Event types recorded in the {@link AgentState} audit log.
- * - `pr_tracked` — A new PR was added to tracking
- * - `pr_merged` — A tracked PR was merged
- * - `pr_closed` — A tracked PR was closed without merge
- * - `pr_dormant` — A PR crossed the dormant threshold
- * - `daily_check` — A daily digest run completed
- * - `comment_posted` — The agent posted a comment on a PR
- */
-export type StateEventType = 'pr_tracked' | 'pr_merged' | 'pr_closed' | 'pr_dormant' | 'daily_check' | 'comment_posted';
-/** An entry in the state audit log. Events are append-only and used for history tracking. */
-export interface StateEvent {
-    id: string;
-    type: StateEventType;
-    /** ISO 8601 timestamp of when the event occurred. */
-    at: string;
-    /** Event-specific payload (e.g., `{ repo: "owner/repo", number: 42 }` for PR events). */
-    data: Record<string, unknown>;
-}
-/** Minimal record of a PR that was closed without being merged, used in the daily digest and dashboard detail view. */
-export interface ClosedPR {
-    url: string;
-    repo: string;
-    number: number;
-    title: string;
-    closedAt: string;
-    closedBy?: string;
-}
-/** Minimal merged PR data persisted in state.json. Repo/number derived from URL at display time. */
-export interface StoredMergedPR {
-    url: string;
-    title: string;
-    mergedAt: string;
-}
-/** Minimal closed PR data persisted in state.json. Repo/number derived from URL at display time. */
-export interface StoredClosedPR {
-    url: string;
-    title: string;
-    closedAt: string;
-}
-/** Minimal record of a PR that was merged, used in the daily digest and dashboard detail view. */
-export interface MergedPR {
-    url: string;
-    repo: string;
-    number: number;
-    title: string;
-    mergedAt: string;
-}
-/**
- * The daily report produced by `PRMonitor.generateDigest()`.
- * Contains all open PRs fetched fresh from GitHub, categorized by status,
- * plus recently closed PRs and summary statistics. This is persisted in
- * `AgentState.lastDigest` so the HTML dashboard can render it.
- */
-export interface DailyDigest {
-    generatedAt: string;
-    /** All open PRs authored by the user, fetched from GitHub Search API. */
-    openPRs: FetchedPR[];
-    /** PRs where the contributor needs to take action. Subset of openPRs where status === 'needs_addressing'. */
-    needsAddressingPRs: FetchedPR[];
-    /** PRs waiting on the maintainer. Subset of openPRs where status === 'waiting_on_maintainer'. */
-    waitingOnMaintainerPRs: FetchedPR[];
-    /** PRs closed without merge in the last 7 days. Surfaced to alert the contributor. */
-    recentlyClosedPRs: ClosedPR[];
-    /** PRs merged in the last 7 days. Surfaced as wins in the dashboard. */
-    recentlyMergedPRs: MergedPR[];
-    /**
-     * PRs manually shelved by the user (excluded from capacity and actionable issues).
-     * Stored as lightweight references — full data is available in `openPRs`.
-     */
-    shelvedPRs: ShelvedPRRef[];
-    /**
-     * PRs that were auto-unshelved this run because a maintainer engaged.
-     * Stored as lightweight references — full data is available in `openPRs`.
-     */
-    autoUnshelvedPRs: ShelvedPRRef[];
-    summary: {
-        totalActivePRs: number;
-        /** Count of PRs requiring contributor action (response, CI fix, conflict resolution, etc.). */
-        totalNeedingAttention: number;
-        /** Lifetime merged PR count across all repos, derived from RepoScore data. */
-        totalMergedAllTime: number;
-        /** Percentage of all-time PRs that were merged (merged / (merged + closed)). */
-        mergeRate: number;
-    };
-}
-/**
- * Root state object persisted to `~/.oss-autopilot/state.json`.
- *
- * In v2 (current), PRs are fetched fresh from GitHub on each run via the Search API.
- * The primary runtime data lives in `lastDigest` and `repoScores`.
- */
-export interface AgentState {
-    /** Schema version. `2` = v2 fresh-fetch architecture. Used by `StateManager` for migrations. */
-    version: number;
-    /** Per-repo quality scores keyed by `"owner/repo"`. Used to prioritize issue search results. */
-    repoScores: Record<string, RepoScore>;
-    config: AgentConfig;
-    /** Append-only audit log of significant events (PR merged, daily check, etc.). */
-    events: StateEvent[];
-    /** ISO timestamp of the last CLI invocation. */
-    lastRunAt: string;
-    /** ISO timestamp of the last daily digest generation. */
-    lastDigestAt?: string;
-    /** Cached daily digest so the HTML dashboard can render without re-fetching from GitHub. */
-    lastDigest?: DailyDigest;
-    /** Monthly merged PR counts keyed by `"YYYY-MM"`. Powers the contribution timeline chart. */
-    monthlyMergedCounts?: Record<string, number>;
-    /** Monthly closed (without merge) PR counts keyed by `"YYYY-MM"`. Powers the timeline and success rate charts. */
-    monthlyClosedCounts?: Record<string, number>;
-    /** Monthly opened PR counts keyed by `"YYYY-MM"`. Combines PRs opened across merged+closed+open sets. */
-    monthlyOpenedCounts?: Record<string, number>;
-    /** Daily activity counts keyed by `"YYYY-MM-DD"`. Powers the activity heatmap chart. */
-    dailyActivityCounts?: Record<string, number>;
-    /** Cached local repo scan results (#84). Avoids re-scanning the filesystem every session. */
-    localRepoCache?: LocalRepoCache;
-    /** All merged PRs stored incrementally. Source of truth for the merged PR detail view. */
-    mergedPRs?: StoredMergedPR[];
-    /** All closed PRs stored incrementally. Source of truth for the closed PR detail view. */
-    closedPRs?: StoredClosedPR[];
-    activeIssues: TrackedIssue[];
-}
-/** Cached results from scanning the filesystem for local git clones (#84). */
-export interface LocalRepoCache {
-    /** Map of "owner/repo" -> local repo info */
-    repos: Record<string, {
-        path: string;
-        exists: boolean;
-        currentBranch: string | null;
-    }>;
-    /** Directories that were scanned */
-    scanPaths: string[];
-    /** ISO 8601 timestamp of when the scan was performed */
-    cachedAt: string;
-}
 /** Filter for excluding repos below a minimum star count from PR count queries. */
 export interface StarFilter {
     minStars: number;
@@ -445,68 +196,6 @@ export interface StarFilter {
  * Returns true if the repo is below the threshold or has unknown star count.
  */
 export declare function isBelowMinStars(stargazersCount: number | undefined, minStars: number): boolean;
-/** Manual status override for a PR, set via dashboard or CLI. Auto-clears when new activity is detected. */
-export interface StatusOverride {
-    status: FetchedPRStatus;
-    setAt: string;
-    /** PR's updatedAt at the time the override was set. Used to detect new activity for auto-clear. */
-    lastActivityAt: string;
-}
-/** User-configurable settings, populated via `/setup-oss` and stored in {@link AgentState}. */
-export interface AgentConfig {
-    /** False until the user completes initial setup via `/setup-oss`. */
-    setupComplete: boolean;
-    setupCompletedAt?: string;
-    maxActivePRs: number;
-    /** Days of inactivity before a PR is marked `dormant`. Default 30. */
-    dormantThresholdDays: number;
-    /** Days of inactivity before a PR is marked `approaching_dormant`. Default 25. */
-    approachingDormantDays: number;
-    /** Issues older than this (by `updated_at`) are filtered from search results. Default 90. */
-    maxIssueAgeDays: number;
-    /** Programming languages to search for issues in (e.g., `["typescript", "javascript"]`). */
-    languages: string[];
-    /** GitHub labels to filter issues by (e.g., `["good first issue", "help wanted"]`). */
-    labels: string[];
-    /** Issue scope tiers to search (e.g., `["beginner", "intermediate"]`). When set, scope tier labels are merged with custom `labels`. When absent, only `labels` is used (legacy behavior). */
-    scope?: IssueScope[];
-    /** Repos to exclude from issue discovery/search, in `"owner/repo"` format. */
-    excludeRepos: string[];
-    /** Organizations to exclude from issue discovery/search (case-insensitive match on owner segment). */
-    excludeOrgs?: string[];
-    /** Repos where the contributor has had PRs merged. Used for prioritization. */
-    trustedProjects: string[];
-    githubUsername: string;
-    /** Minimum {@link RepoScore} to include a repo in search results. Default 4. */
-    minRepoScoreThreshold: number;
-    /** User's GitHub starred repos, fetched periodically for prioritized issue discovery. */
-    starredRepos: string[];
-    starredReposLastFetched?: string;
-    /** Whether to show the health check notification on session start. Default true. */
-    showHealthCheck?: boolean;
-    /** Whether to squash commits before marking PR ready. `true` (default), `false`, or `"ask"`. */
-    squashByDefault?: boolean | 'ask';
-    /** Directories to scan for local git clones (#84). Falls back to default paths if not set. */
-    localRepoScanPaths?: string[];
-    /** Minimum GitHub star count for Phase 2 (general search) results. Default 50. Phases 0/1 are exempt. */
-    minStars?: number;
-    /** Whether to include documentation-only issues in search results. Default true. */
-    includeDocIssues?: boolean;
-    /** Repos known to have anti-AI contribution policies, in `"owner/repo"` format. Filtered from search results automatically. */
-    aiPolicyBlocklist?: string[];
-    /** PR URLs manually shelved by the user. Shelved PRs are excluded from capacity and actionable issues. Auto-unshelved when maintainers engage. */
-    shelvedPRUrls?: string[];
-    /** Issue URLs dismissed by the user, mapped to ISO timestamp of when dismissed. Issues with new responses after the dismiss timestamp resurface automatically. */
-    dismissedIssues?: Record<string, string>;
-    /** Manual status overrides for PRs. Maps PR URL to override metadata. Auto-clears when the PR has new activity. */
-    statusOverrides?: Record<string, StatusOverride>;
-    /** Path to the user's curated issue list file. Replaces config.md as the primary source for detectIssueList(). */
-    issueListPath?: string;
-    /** Project categories the user is interested in (e.g., devtools, nonprofit). Used to prioritize search results. */
-    projectCategories?: ProjectCategory[];
-    /** GitHub organizations the user wants to prioritize in issue search. Org names only (not owner/repo). */
-    preferredOrgs?: string[];
-}
 /** Status of a user's comment thread on a GitHub issue. */
 export type IssueConversationStatus = 'new_response' | 'waiting' | 'acknowledged';
 /** Base fields shared by all issue conversation states. */
@@ -544,10 +233,8 @@ export type CommentedIssue = CommentedIssueWithResponse | CommentedIssueWithoutR
 export declare const DEFAULT_CONFIG: AgentConfig;
 /** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v2 architecture. */
 export declare const INITIAL_STATE: AgentState;
-export declare const PROJECT_CATEGORIES: readonly ["nonprofit", "devtools", "infrastructure", "web-frameworks", "data-ml", "education"];
-export type ProjectCategory = (typeof PROJECT_CATEGORIES)[number];
-export declare const ISSUE_SCOPES: readonly ["beginner", "intermediate", "advanced"];
-export type IssueScope = (typeof ISSUE_SCOPES)[number];
+export declare const PROJECT_CATEGORIES: ("nonprofit" | "devtools" | "infrastructure" | "web-frameworks" | "data-ml" | "education")[];
+export declare const ISSUE_SCOPES: ("advanced" | "beginner" | "intermediate")[];
 export declare const SCOPE_LABELS: Record<IssueScope, string[]>;
 /** Priority tier for issue search results. Ordered: merged_pr > preferred_org > starred > normal. */
 export type SearchPriority = 'merged_pr' | 'preferred_org' | 'starred' | 'normal';
@@ -561,4 +248,3 @@ export interface IssueCandidate {
     viabilityScore: number;
     searchPriority: SearchPriority;
 }
-export {};

package/dist/core/types.js

@@ -1,6 +1,7 @@
 /**
  * Core types for the Open Source Contribution Agent
  */
+import { AgentConfigSchema, AgentStateSchema, ProjectCategorySchema, IssueScopeSchema } from './state-schema.js';
 /**
  * Check if a repo should be excluded based on its star count.
  * Returns true if the repo is below the threshold or has unknown star count.
@@ -8,49 +9,14 @@
 export function isBelowMinStars(stargazersCount, minStars) {
     return stargazersCount === undefined || stargazersCount < minStars;
 }
+// ── Schema-derived constants ─────────────────────────────────────────
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
-export const DEFAULT_CONFIG = {
-    setupComplete: false,
-    maxActivePRs: 10,
-    dormantThresholdDays: 30,
-    approachingDormantDays: 25,
-    maxIssueAgeDays: 90,
-    languages: ['typescript', 'javascript'],
-    labels: ['good first issue', 'help wanted'],
-    excludeRepos: [],
-    trustedProjects: [],
-    githubUsername: '',
-    minRepoScoreThreshold: 4,
-    starredRepos: [],
-    squashByDefault: true,
-    minStars: 50,
-    includeDocIssues: true,
-    aiPolicyBlocklist: ['matplotlib/matplotlib'],
-    shelvedPRUrls: [],
-    dismissedIssues: {},
-    projectCategories: [],
-    preferredOrgs: [],
-};
+export const DEFAULT_CONFIG = AgentConfigSchema.parse({});
 /** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v2 architecture. */
-export const INITIAL_STATE = {
-    version: 2, // v2: Fresh GitHub fetching
-    activeIssues: [],
-    repoScores: {},
-    config: DEFAULT_CONFIG,
-    events: [],
-    lastRunAt: new Date().toISOString(),
-};
-// -- Project category types --
-export const PROJECT_CATEGORIES = [
-    'nonprofit',
-    'devtools',
-    'infrastructure',
-    'web-frameworks',
-    'data-ml',
-    'education',
-];
-// -- Issue scope types --
-export const ISSUE_SCOPES = ['beginner', 'intermediate', 'advanced'];
+export const INITIAL_STATE = AgentStateSchema.parse({ version: 2 });
+// ── Const arrays (derived from Zod schemas for runtime iteration) ────
+export const PROJECT_CATEGORIES = ProjectCategorySchema.options;
+export const ISSUE_SCOPES = IssueScopeSchema.options;
 export const SCOPE_LABELS = {
     beginner: ['good first issue', 'help wanted', 'easy', 'up-for-grabs', 'first-timers-only', 'beginner'],
     intermediate: ['enhancement', 'feature', 'feature-request', 'contributions welcome'],

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.60.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -50,13 +50,15 @@
   "dependencies": {
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.1",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
   },
   "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 +70,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"
   }
 }