@oss-scout/core 0.2.1 → 0.4.0

package/dist/core/search-phases.js

@@ -5,9 +5,9 @@
  * caching, spam-filtering, and batched repo search logic.
  */
 import { SCOPE_LABELS, } from "./types.js";
-import { errorMessage, isRateLimitError } from "./errors.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
 import { debug, warn } from "./logger.js";
-import { getHttpCache, cachedTimeBased } from "./http-cache.js";
+import { getHttpCache } from "./http-cache.js";
 import { detectLabelFarmingRepos, } from "./issue-filtering.js";
 import { extractRepoFromUrl, sleep } from "./utils.js";
 import { getSearchBudgetTracker } from "./search-budget.js";
@@ -95,20 +95,166 @@ const SEARCH_CACHE_TTL_MS = 15 * 60 * 1000;
  */
 export async function cachedSearchIssues(octokit, params) {
     const cacheKey = `search:${params.q}:${params.sort}:${params.order}:${params.per_page}`;
-    return cachedTimeBased(getHttpCache(), cacheKey, SEARCH_CACHE_TTL_MS, async () => {
-        const tracker = getSearchBudgetTracker();
-        await tracker.waitForBudget();
+    const cache = getHttpCache();
+    // Check cache first
+    const cached = cache.getIfFresh(cacheKey, SEARCH_CACHE_TTL_MS);
+    if (cached) {
+        debug(MODULE, `Search cache hit for query`);
+        return cached;
+    }
+    // Fetch from API
+    const tracker = getSearchBudgetTracker();
+    await tracker.waitForBudget();
+    let data;
+    try {
+        const response = await octokit.search.issuesAndPullRequests(params);
+        data = response.data;
+    }
+    finally {
+        tracker.recordCall();
+    }
+    // Only cache non-empty results to prevent poisoning from rate-limited responses
+    if (data.items.length > 0) {
+        cache.set(cacheKey, "", data);
+    }
+    else {
+        debug(MODULE, `Skipping cache for empty search result (possible rate limit artifact)`);
+    }
+    return data;
+}
+// ── REST-based search functions ──
+/**
+ * Fetch issues from maintained repos using REST API (no Search API quota).
+ *
+ * Checks each repo for recent push activity and star threshold,
+ * then fetches open issues via `GET /repos/{owner}/{repo}/issues`.
+ * Falls back to the caller to use Search API if this doesn't yield enough.
+ */
+export async function fetchIssuesFromMaintainedRepos(octokit, repos, minStars, maxResults) {
+    const items = [];
+    for (const repoFullName of repos) {
+        if (items.length >= maxResults * 3)
+            break;
+        const [owner, repo] = repoFullName.split("/");
+        if (!owner || !repo)
+            continue;
         try {
-            const { data } = await octokit.search.issuesAndPullRequests(params);
-            return data;
+            const { data: repoData } = await octokit.repos.get({ owner, repo });
+            if (!repoData.pushed_at)
+                continue;
+            const pushedAt = new Date(repoData.pushed_at);
+            const thirtyDaysAgo = new Date();
+            thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+            if (pushedAt < thirtyDaysAgo)
+                continue;
+            if ((repoData.stargazers_count ?? 0) < minStars)
+                continue;
+            if (repoData.archived)
+                continue;
+            const { data: issues } = await octokit.issues.listForRepo({
+                owner,
+                repo,
+                state: "open",
+                sort: "created",
+                direction: "desc",
+                per_page: 5,
+            });
+            // Filter out pull requests and assigned issues (REST endpoint returns both)
+            const realIssues = issues.filter((i) => !i.pull_request && !i.assignee);
+            for (const issue of realIssues) {
+                items.push({
+                    html_url: issue.html_url,
+                    repository_url: `https://api.github.com/repos/${repoFullName}`,
+                    updated_at: issue.updated_at ?? "",
+                    title: issue.title,
+                    labels: issue.labels,
+                });
+            }
+            await sleep(INTER_QUERY_DELAY_MS);
         }
-        finally {
-            // Always record the call — failed requests still consume GitHub rate limit points
-            tracker.recordCall();
+        catch (error) {
+            if (getHttpStatusCode(error) === 401)
+                throw error;
+            if (isRateLimitError(error)) {
+                warn(MODULE, `Rate limit hit fetching issues from ${repoFullName}:`, errorMessage(error));
+                break;
+            }
+            warn(MODULE, `Error fetching issues from ${repoFullName}:`, errorMessage(error));
         }
-    });
+    }
+    return items;
 }
 // ── Search infrastructure ──
+/**
+ * Fetch open issues from known repos using REST API (no Search API quota).
+ * Used by Phase 0 (merged-PR repos) and Phase 1 (starred repos).
+ *
+ * Instead of the Search API (`octokit.search.issuesAndPullRequests`), this
+ * calls `GET /repos/{owner}/{repo}/issues` which counts against the much
+ * larger Core API rate limit and avoids consuming the scarce Search quota.
+ */
+export async function fetchIssuesFromKnownRepos(octokit, vetter, repos, labels, maxResults, priority, filterFn) {
+    const candidates = [];
+    let failedRepos = 0;
+    let rateLimitFailures = 0;
+    for (let i = 0; i < repos.length; i++) {
+        if (candidates.length >= maxResults)
+            break;
+        // Delay between repos to avoid REST secondary rate limits
+        if (i > 0)
+            await sleep(INTER_QUERY_DELAY_MS);
+        const repoFullName = repos[i];
+        const [owner, repo] = repoFullName.split("/");
+        try {
+            const response = await octokit.issues.listForRepo({
+                owner,
+                repo,
+                state: "open",
+                sort: "created",
+                direction: "desc",
+                per_page: 5,
+                ...(labels.length > 0 ? { labels: labels.join(",") } : {}),
+            });
+            // Filter out pull requests (REST issues endpoint returns both) and assigned issues
+            const issuesOnly = response.data.filter((item) => !("pull_request" in item) && !item.assignee);
+            const mapped = issuesOnly.map((issue) => ({
+                html_url: issue.html_url,
+                repository_url: `https://api.github.com/repos/${repoFullName}`,
+                updated_at: issue.updated_at ?? "",
+                title: issue.title,
+                labels: issue.labels,
+            }));
+            if (mapped.length > 0) {
+                const filtered = filterFn(mapped);
+                if (filtered.length > 0) {
+                    const remainingNeeded = maxResults - candidates.length;
+                    const { candidates: vetted, rateLimitHit: vetRateLimitHit } = await vetter.vetIssuesParallel(filtered
+                        .slice(0, remainingNeeded * 2)
+                        .map((item) => item.html_url), remainingNeeded, priority);
+                    candidates.push(...vetted);
+                    if (vetRateLimitHit)
+                        rateLimitFailures++;
+                }
+            }
+        }
+        catch (error) {
+            if (getHttpStatusCode(error) === 401)
+                throw error;
+            failedRepos++;
+            if (isRateLimitError(error)) {
+                rateLimitFailures++;
+            }
+            warn(MODULE, `Error fetching issues from ${repoFullName}:`, errorMessage(error));
+        }
+    }
+    const allReposFailed = failedRepos === repos.length && repos.length > 0;
+    const rateLimitHit = rateLimitFailures > 0;
+    if (allReposFailed) {
+        warn(MODULE, `All ${repos.length} repo(s) failed for ${priority} phase. ` +
+            `This may indicate a systemic issue (rate limit, auth, network).`);
+    }
+    return { candidates, allReposFailed, rateLimitHit };
+}
 /**
  * Search across chunked labels with deduplication.
  *

package/dist/core/types.d.ts

@@ -19,7 +19,7 @@ export interface ProjectHealth {
     failureReason?: string;
 }
 /** Priority tier for issue search results. */
-export type SearchPriority = "merged_pr" | "preferred_org" | "starred" | "normal";
+export type SearchPriority = "merged_pr" | "starred" | "normal";
 /** A fully vetted issue candidate with scoring. */
 export interface IssueCandidate {
     issue: TrackedIssue;

package/dist/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { createScout, OssScout } from "./scout.js";
 export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from "./core/types.js";
-export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, SearchStrategy, } from "./core/schemas.js";
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from "./core/schemas.js";
+export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, SearchStrategy, SkippedIssue, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 export { IssueDiscovery } from "./core/issue-discovery.js";
 export { IssueVetter, type ScoutStateReader } from "./core/issue-vetting.js";

package/dist/index.js

@@ -17,7 +17,7 @@
 // Main API
 export { createScout, OssScout } from "./scout.js";
 // Schemas (for consumers who need runtime validation)
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
 // Utilities
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 // Internal classes (for advanced use)

package/dist/scout.d.ts

@@ -5,7 +5,7 @@
  * Implements ScoutStateReader to bridge state with the search engine.
  */
 import type { ScoutStateReader } from "./core/issue-vetting.js";
-import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate } from "./core/schemas.js";
+import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue } from "./core/schemas.js";
 import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from "./core/types.js";
 import { GistStateStore } from "./core/gist-state-store.js";
 /**
@@ -44,6 +44,7 @@ export declare class OssScout implements ScoutStateReader {
     constructor(githubToken: string, initialState: ScoutState, gistStore?: GistStateStore | null);
     /**
      * Multi-strategy issue search. Returns scored, sorted candidates.
+     * Automatically culls expired skip entries and filters skipped issues.
      */
     search(options?: SearchOptions): Promise<SearchResult>;
     /**
@@ -59,7 +60,6 @@ export declare class OssScout implements ScoutStateReader {
     private classifyVetResult;
     getReposWithMergedPRs(): string[];
     getStarredRepos(): string[];
-    getPreferredOrgs(): string[];
     getProjectCategories(): ProjectCategory[];
     getRepoScore(repo: string): number | null;
     /** Get current preferences (read-only). */
@@ -101,6 +101,31 @@ export declare class OssScout implements ScoutStateReader {
      * Clear all saved results.
      */
     clearResults(): void;
+    /**
+     * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
+     */
+    skipIssue(url: string, metadata?: {
+        repo?: string;
+        number?: number;
+        title?: string;
+    }): void;
+    /**
+     * Get all skipped issues.
+     */
+    getSkippedIssues(): SkippedIssue[];
+    /**
+     * Remove a specific issue from the skip list.
+     */
+    unskipIssue(url: string): void;
+    /**
+     * Clear all skipped issues.
+     */
+    clearSkippedIssues(): void;
+    /**
+     * Remove skipped issues older than maxDays (default 90). Called automatically during search.
+     * @returns The number of expired entries that were removed.
+     */
+    cullExpiredSkips(maxDays?: number): number;
     /**
      * Check if state has uncommitted changes.
      */

package/dist/scout.js

@@ -119,12 +119,17 @@ export class OssScout {
     // ── Search ──────────────────────────────────────────────────────────
     /**
      * Multi-strategy issue search. Returns scored, sorted candidates.
+     * Automatically culls expired skip entries and filters skipped issues.
      */
     async search(options) {
+        // Auto-cull expired skips before searching
+        this.cullExpiredSkips();
+        const skippedUrls = new Set((this.state.skippedIssues ?? []).map((s) => s.url));
         const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
         const { candidates, strategiesUsed } = await discovery.searchIssues({
             maxResults: options?.maxResults,
             strategies: options?.strategies,
+            skippedUrls,
         });
         this.state.lastSearchAt = new Date().toISOString();
         this.dirty = true;
@@ -234,9 +239,6 @@ export class OssScout {
     getStarredRepos() {
         return this.state.starredRepos;
     }
-    getPreferredOrgs() {
-        return this.state.preferences.preferredOrgs;
-    }
     getProjectCategories() {
         return this.state.preferences.projectCategories;
     }
@@ -369,6 +371,70 @@ export class OssScout {
         this.state.savedResults = [];
         this.dirty = true;
     }
+    // ── Skip List ───────────────────────────────────────────────────────
+    /**
+     * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
+     */
+    skipIssue(url, metadata) {
+        const existing = this.state.skippedIssues ?? [];
+        if (existing.some((s) => s.url === url))
+            return; // already skipped
+        this.state.skippedIssues = [
+            ...existing,
+            {
+                url,
+                repo: metadata?.repo ?? "",
+                number: metadata?.number ?? 0,
+                title: metadata?.title ?? "",
+                skippedAt: new Date().toISOString(),
+            },
+        ];
+        // Also remove from saved results if present
+        if (this.state.savedResults) {
+            this.state.savedResults = this.state.savedResults.filter((r) => r.issueUrl !== url);
+        }
+        this.dirty = true;
+    }
+    /**
+     * Get all skipped issues.
+     */
+    getSkippedIssues() {
+        return this.state.skippedIssues ?? [];
+    }
+    /**
+     * Remove a specific issue from the skip list.
+     */
+    unskipIssue(url) {
+        this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => s.url !== url);
+        this.dirty = true;
+    }
+    /**
+     * Clear all skipped issues.
+     */
+    clearSkippedIssues() {
+        this.state.skippedIssues = [];
+        this.dirty = true;
+    }
+    /**
+     * Remove skipped issues older than maxDays (default 90). Called automatically during search.
+     * @returns The number of expired entries that were removed.
+     */
+    cullExpiredSkips(maxDays = 90) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - maxDays);
+        const before = (this.state.skippedIssues ?? []).length;
+        this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => {
+            const d = new Date(s.skippedAt);
+            if (isNaN(d.getTime())) {
+                return true; // keep entries with invalid dates rather than silently dropping
+            }
+            return d >= cutoff;
+        });
+        const culled = before - this.state.skippedIssues.length;
+        if (culled > 0)
+            this.dirty = true;
+        return culled;
+    }
     // ── Persistence ─────────────────────────────────────────────────────
     /**
      * Check if state has uncommitted changes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.2.1",
-  "description": "Find open source issues personalized to your contribution history",
+  "version": "0.4.0",
+  "description": "Personalized GitHub issue finder with multi-strategy search, deep vetting, and viability scoring — CLI, library, MCP server, and Claude Code plugin",
   "type": "module",
   "bin": {
     "oss-scout": "./dist/cli.bundle.cjs"
@@ -21,23 +21,17 @@
     "!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"
+    "contributions",
+    "claude",
+    "mcp-server",
+    "contribution-finder",
+    "personalized"
   ],
   "author": "John Costa",
   "license": "MIT",
@@ -66,5 +60,14 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
+  },
+  "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"
   }
-}
+}

package/dist/core/concurrency.d.ts

@@ -1,6 +0,0 @@
-/**
- * Runs a worker pool that processes items with bounded concurrency.
- * N workers consume from a shared index. On any worker error, remaining
- * workers are aborted via a shared flag and the error is propagated.
- */
-export declare function runWorkerPool<T>(items: T[], worker: (item: T) => Promise<void>, concurrency: number): Promise<void>;

package/dist/core/concurrency.js

@@ -1,25 +0,0 @@
-/**
- * Runs a worker pool that processes items with bounded concurrency.
- * N workers consume from a shared index. On any worker error, remaining
- * workers are aborted via a shared flag and the error is propagated.
- */
-export async function runWorkerPool(items, worker, concurrency) {
-    let index = 0;
-    let aborted = false;
-    const poolWorker = async () => {
-        while (index < items.length) {
-            if (aborted)
-                break;
-            const item = items[index++];
-            try {
-                await worker(item);
-            }
-            catch (err) {
-                aborted = true;
-                throw err;
-            }
-        }
-    };
-    const workerCount = Math.min(concurrency, items.length);
-    await Promise.all(Array.from({ length: workerCount }, () => poolWorker()));
-}