@oss-scout/core 0.1.0

package/dist/scout.js

@@ -0,0 +1,391 @@
+/**
+ * OssScout — the public API for oss-scout.
+ *
+ * Provides personalized issue discovery, vetting, and scoring.
+ * Implements ScoutStateReader to bridge state with the search engine.
+ */
+import { IssueDiscovery } from './core/issue-discovery.js';
+import { ScoutStateSchema } from './core/schemas.js';
+import { GistStateStore, mergeStates } from './core/gist-state-store.js';
+import { getOctokit } from './core/github.js';
+import { loadLocalState } from './core/local-state.js';
+import { warn } from './core/logger.js';
+/**
+ * Create an OssScout instance.
+ *
+ * @param config - Configuration including GitHub token and persistence mode
+ * @returns A ready-to-use OssScout instance
+ *
+ * @example
+ * ```typescript
+ * import { createScout } from '@oss-scout/core';
+ *
+ * // Standalone with gist persistence
+ * const scout = await createScout({ githubToken: 'ghp_...', persistence: 'gist' });
+ *
+ * // As a library (host application provides state)
+ * const scout = await createScout({
+ *   githubToken: 'ghp_...',
+ *   persistence: 'provided',
+ *   initialState: myState,
+ * });
+ * ```
+ */
+export async function createScout(config) {
+    let state;
+    let gistStore = null;
+    if (config.persistence === 'provided') {
+        state = config.initialState;
+    }
+    else if (config.persistence === 'gist') {
+        gistStore = new GistStateStore(getOctokit(config.githubToken));
+        const result = await gistStore.bootstrap();
+        if (result.degraded) {
+            warn('scout', 'Gist sync unavailable — running in offline mode. Changes will only be saved locally.');
+        }
+        const localState = loadLocalState();
+        state = mergeStates(localState, result.state);
+        if (config.gistId) {
+            state.gistId = config.gistId;
+        }
+        else if (result.gistId) {
+            state.gistId = result.gistId;
+        }
+    }
+    else {
+        state = ScoutStateSchema.parse({ version: 1 });
+    }
+    return new OssScout(config.githubToken, state, gistStore);
+}
+/**
+ * Main oss-scout class. Provides search, vetting, and state management.
+ *
+ * Implements ScoutStateReader so the search engine can read state
+ * without knowing about the persistence layer.
+ */
+export class OssScout {
+    githubToken;
+    gistStore;
+    state;
+    dirty = false;
+    constructor(githubToken, initialState, gistStore = null) {
+        this.githubToken = githubToken;
+        this.gistStore = gistStore;
+        this.state = initialState;
+    }
+    // ── Search ──────────────────────────────────────────────────────────
+    /**
+     * Multi-strategy issue search. Returns scored, sorted candidates.
+     */
+    async search(options) {
+        const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
+        const { candidates, strategiesUsed } = await discovery.searchIssues({
+            maxResults: options?.maxResults,
+            strategies: options?.strategies,
+        });
+        this.state.lastSearchAt = new Date().toISOString();
+        this.dirty = true;
+        return {
+            candidates,
+            excludedRepos: this.state.preferences.excludeRepos,
+            aiPolicyBlocklist: this.state.preferences.aiPolicyBlocklist,
+            rateLimitWarning: discovery.rateLimitWarning ?? undefined,
+            strategiesUsed,
+        };
+    }
+    /**
+     * Vet a single issue URL for claimability.
+     */
+    async vetIssue(issueUrl) {
+        const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
+        return discovery.vetIssue(issueUrl);
+    }
+    // ── Batch Vetting ───────────────────────────────────────────────────
+    /**
+     * Re-vet all saved results with bounded concurrency.
+     * Classifies each as still_available, claimed, has_pr, closed, or error.
+     * Optionally prunes unavailable issues from saved results.
+     */
+    async vetList(options) {
+        const saved = this.getSavedResults();
+        const concurrency = options?.concurrency ?? 5;
+        const results = [];
+        const pending = new Map();
+        for (const item of saved) {
+            const task = this.vetIssue(item.issueUrl)
+                .then((candidate) => {
+                results.push({
+                    issueUrl: item.issueUrl,
+                    repo: item.repo,
+                    number: item.number,
+                    title: item.title,
+                    status: this.classifyVetResult(candidate),
+                    recommendation: candidate.recommendation,
+                    viabilityScore: candidate.viabilityScore,
+                });
+            })
+                .catch((error) => {
+                const msg = error instanceof Error ? error.message : String(error);
+                const isGone = msg.includes('Not Found') || msg.includes('410');
+                results.push({
+                    issueUrl: item.issueUrl,
+                    repo: item.repo,
+                    number: item.number,
+                    title: item.title,
+                    status: isGone ? 'closed' : 'error',
+                    errorMessage: msg,
+                });
+            })
+                .finally(() => {
+                pending.delete(item.issueUrl);
+            });
+            pending.set(item.issueUrl, task);
+            if (pending.size >= concurrency) {
+                await Promise.race(pending.values());
+            }
+        }
+        await Promise.allSettled(pending.values());
+        const summary = {
+            total: results.length,
+            stillAvailable: results.filter((r) => r.status === 'still_available').length,
+            claimed: results.filter((r) => r.status === 'claimed').length,
+            closed: results.filter((r) => r.status === 'closed').length,
+            hasPR: results.filter((r) => r.status === 'has_pr').length,
+            errors: results.filter((r) => r.status === 'error').length,
+        };
+        let prunedCount;
+        if (options?.prune) {
+            const unavailableUrls = new Set(results.filter((r) => r.status !== 'still_available').map((r) => r.issueUrl));
+            const before = (this.state.savedResults ?? []).length;
+            this.state.savedResults = (this.state.savedResults ?? []).filter((r) => !unavailableUrls.has(r.issueUrl));
+            prunedCount = before - (this.state.savedResults?.length ?? 0);
+            this.dirty = true;
+        }
+        return { results, summary, prunedCount };
+    }
+    classifyVetResult(candidate) {
+        const checks = candidate.vettingResult.checks;
+        if (!checks.noExistingPR)
+            return 'has_pr';
+        if (!checks.notClaimed)
+            return 'claimed';
+        return 'still_available';
+    }
+    // ── State Reads (ScoutStateReader implementation) ───────────────────
+    getReposWithMergedPRs() {
+        const repoCounts = new Map();
+        for (const pr of this.state.mergedPRs ?? []) {
+            const repo = this.extractRepoFromUrl(pr.url);
+            if (repo) {
+                repoCounts.set(repo, (repoCounts.get(repo) ?? 0) + 1);
+            }
+        }
+        // Sort by count descending
+        return [...repoCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([repo]) => repo);
+    }
+    getStarredRepos() {
+        return this.state.starredRepos;
+    }
+    getPreferredOrgs() {
+        return this.state.preferences.preferredOrgs;
+    }
+    getProjectCategories() {
+        return this.state.preferences.projectCategories;
+    }
+    getRepoScore(repo) {
+        const score = this.state.repoScores[repo];
+        return score ? score.score : null;
+    }
+    /** Get current preferences (read-only). */
+    getPreferences() {
+        return this.state.preferences;
+    }
+    /** Get repo score record for a specific repository. */
+    getRepoScoreRecord(repo) {
+        return this.state.repoScores[repo];
+    }
+    // ── State Mutations ─────────────────────────────────────────────────
+    /**
+     * Record that a PR was merged in this repo.
+     * Updates the merged PRs list and recalculates the repo score.
+     */
+    recordMergedPR(pr) {
+        const existing = this.state.mergedPRs ?? [];
+        // Deduplicate by URL
+        if (existing.some((p) => p.url === pr.url))
+            return;
+        this.state.mergedPRs = [
+            ...existing,
+            { url: pr.url, title: pr.title, mergedAt: pr.mergedAt },
+        ];
+        this.updateRepoScoreFromPRs(pr.repo);
+        this.dirty = true;
+    }
+    /**
+     * Record that a PR was closed without merge.
+     */
+    recordClosedPR(pr) {
+        const existing = this.state.closedPRs ?? [];
+        if (existing.some((p) => p.url === pr.url))
+            return;
+        this.state.closedPRs = [
+            ...existing,
+            { url: pr.url, title: pr.title, closedAt: pr.closedAt },
+        ];
+        this.updateRepoScoreFromPRs(pr.repo);
+        this.dirty = true;
+    }
+    /**
+     * Update repo score with observed signals.
+     */
+    updateRepoScore(repo, update) {
+        const existing = this.state.repoScores[repo];
+        const base = existing ?? {
+            repo,
+            score: 5,
+            mergedPRCount: 0,
+            closedWithoutMergeCount: 0,
+            avgResponseDays: null,
+            lastEvaluatedAt: new Date().toISOString(),
+            signals: {
+                hasActiveMaintainers: false,
+                isResponsive: false,
+                hasHostileComments: false,
+            },
+        };
+        const updated = {
+            ...base,
+            ...update,
+            repo,
+            lastEvaluatedAt: new Date().toISOString(),
+            signals: { ...base.signals, ...(update.signals ?? {}) },
+        };
+        // Recalculate score
+        updated.score = this.calculateScore(updated);
+        this.state.repoScores[repo] = updated;
+        this.dirty = true;
+    }
+    /**
+     * Update user preferences.
+     */
+    updatePreferences(updates) {
+        this.state.preferences = { ...this.state.preferences, ...updates };
+        this.dirty = true;
+    }
+    /**
+     * Update starred repos cache.
+     */
+    setStarredRepos(repos) {
+        this.state.starredRepos = repos;
+        this.state.starredReposLastFetched = new Date().toISOString();
+        this.dirty = true;
+    }
+    // ── Saved Results ───────────────────────────────────────────────────
+    /**
+     * Save search candidates to state, deduplicating by URL.
+     * If a candidate already exists, updates score/recommendation/lastSeenAt
+     * but preserves firstSeenAt.
+     */
+    saveResults(candidates) {
+        const now = new Date().toISOString();
+        const existing = new Map((this.state.savedResults ?? []).map((r) => [r.issueUrl, r]));
+        for (const c of candidates) {
+            const prev = existing.get(c.issue.url);
+            existing.set(c.issue.url, {
+                issueUrl: c.issue.url,
+                repo: c.issue.repo,
+                number: c.issue.number,
+                title: c.issue.title,
+                labels: c.issue.labels,
+                recommendation: c.recommendation,
+                viabilityScore: c.viabilityScore,
+                searchPriority: c.searchPriority,
+                firstSeenAt: prev?.firstSeenAt ?? now,
+                lastSeenAt: now,
+                lastScore: c.viabilityScore,
+            });
+        }
+        this.state.savedResults = [...existing.values()];
+        this.dirty = true;
+    }
+    /**
+     * Get all saved results.
+     */
+    getSavedResults() {
+        return this.state.savedResults ?? [];
+    }
+    /**
+     * Clear all saved results.
+     */
+    clearResults() {
+        this.state.savedResults = [];
+        this.dirty = true;
+    }
+    // ── Persistence ─────────────────────────────────────────────────────
+    /**
+     * Check if state has uncommitted changes.
+     */
+    isDirty() {
+        return this.dirty;
+    }
+    /**
+     * Push pending changes to the persistence layer.
+     * Pushes to gist if gist persistence is configured.
+     */
+    async checkpoint() {
+        if (!this.dirty)
+            return true;
+        this.state.lastRunAt = new Date().toISOString();
+        if (this.gistStore) {
+            const ok = await this.gistStore.push(this.state);
+            if (!ok)
+                return false;
+        }
+        this.dirty = false;
+        return true;
+    }
+    /**
+     * Get the full state snapshot for serialization or external consumption.
+     */
+    getState() {
+        return this.state;
+    }
+    // ── Private helpers ─────────────────────────────────────────────────
+    extractRepoFromUrl(url) {
+        const match = url.match(/github\.com\/([^/]+\/[^/]+)\//);
+        return match ? match[1] : null;
+    }
+    updateRepoScoreFromPRs(repo) {
+        const mergedCount = (this.state.mergedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
+        const closedCount = (this.state.closedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
+        this.updateRepoScore(repo, {
+            mergedPRCount: mergedCount,
+            closedWithoutMergeCount: closedCount,
+            lastMergedAt: mergedCount > 0
+                ? (this.state.mergedPRs ?? [])
+                    .filter((p) => this.extractRepoFromUrl(p.url) === repo)
+                    .sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]
+                    ?.mergedAt
+                : undefined,
+        });
+    }
+    /**
+     * Calculate repo score (1-10) from observed data.
+     * base 5, +1 per merged PR (max +3), -1 per closed-without-merge (max -3),
+     * +1 responsive, +1 active maintainers, -2 hostile comments, clamped 1-10
+     */
+    calculateScore(repoScore) {
+        let score = 5;
+        score += Math.min(repoScore.mergedPRCount, 3);
+        score -= Math.min(repoScore.closedWithoutMergeCount, 3);
+        if (repoScore.signals.isResponsive)
+            score += 1;
+        if (repoScore.signals.hasActiveMaintainers)
+            score += 1;
+        if (repoScore.signals.hasHostileComments)
+            score -= 2;
+        return Math.max(1, Math.min(10, score));
+    }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@oss-scout/core",
+  "version": "0.1.0",
+  "description": "Find open source issues personalized to your contribution history",
+  "type": "module",
+  "bin": {
+    "oss-scout": "./dist/cli.bundle.cjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/core/types.js",
+      "types": "./dist/core/types.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "!dist/**/*.map",
+    "!dist/core/test-utils.*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "bundle": "esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --minify --sourcemap --outfile=dist/cli.bundle.cjs",
+    "start": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm run build && pnpm run bundle"
+  },
+  "keywords": [
+    "open-source",
+    "github",
+    "issue-discovery",
+    "cli",
+    "vetting",
+    "contributions"
+  ],
+  "author": "John Costa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/costajohnt/oss-scout.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/costajohnt/oss-scout#readme",
+  "bugs": {
+    "url": "https://github.com/costajohnt/oss-scout/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@octokit/plugin-throttling": "^11.0.3",
+    "@octokit/rest": "^22.0.1",
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "esbuild": "^0.27.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}