@oss-scout/core 0.1.0

package/dist/core/issue-filtering.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Issue Filtering — pure functions for filtering and spam detection on search results.
+ *
+ * Extracted from issue-discovery.ts to isolate filtering logic:
+ * label farming detection, doc-only filtering, per-repo caps, templated title detection.
+ */
+/** Minimal shape of a GitHub search result item (from octokit.search.issuesAndPullRequests) */
+export interface GitHubSearchItem {
+    html_url: string;
+    repository_url: string;
+    updated_at: string;
+    title?: string;
+    labels?: Array<{
+        name?: string;
+    } | string>;
+    [key: string]: unknown;
+}
+/** Labels that indicate documentation-only issues. */
+export declare const DOC_ONLY_LABELS: Set<string>;
+/**
+ * Check if an issue's labels are ALL documentation-related.
+ * Issues with mixed labels (e.g., "good first issue" + "documentation") pass through.
+ * Issues with no labels are not considered doc-only.
+ */
+export declare function isDocOnlyIssue(item: GitHubSearchItem): boolean;
+/** Known beginner-type label names used to detect label-farming repos. */
+export declare const BEGINNER_LABELS: Set<string>;
+/** Check if a single issue has an excessive number of beginner labels (>= 5). */
+export declare function isLabelFarming(item: GitHubSearchItem): boolean;
+/** Detect mass-created issue titles like "Add Trivia Question 61" or "Create Entry #5". */
+export declare function hasTemplatedTitle(title: string): boolean;
+/**
+ * Batch-analyze search items to detect label-farming repositories.
+ * Returns a Set of repo full names (owner/repo) that appear to be spam.
+ *
+ * A repo is flagged if:
+ * - ANY single issue has >= 5 beginner labels (strong individual signal), OR
+ * - It has >= 3 issues with templated titles (batch signal)
+ */
+export declare function detectLabelFarmingRepos(items: GitHubSearchItem[]): Set<string>;
+/**
+ * Apply per-repo cap to candidates.
+ * Keeps at most `maxPerRepo` issues from any single repo.
+ * Maintains the existing sort order — first N from each repo are kept,
+ * excess issues from over-represented repos are dropped.
+ */
+export declare function applyPerRepoCap<T extends {
+    issue: {
+        repo: string;
+    };
+}>(candidates: T[], maxPerRepo: number): T[];

package/dist/core/issue-filtering.js

@@ -0,0 +1,103 @@
+/**
+ * Issue Filtering — pure functions for filtering and spam detection on search results.
+ *
+ * Extracted from issue-discovery.ts to isolate filtering logic:
+ * label farming detection, doc-only filtering, per-repo caps, templated title detection.
+ */
+/** Labels that indicate documentation-only issues. */
+export const DOC_ONLY_LABELS = new Set(['documentation', 'docs', 'typo', 'spelling']);
+/**
+ * Check if an issue's labels are ALL documentation-related.
+ * Issues with mixed labels (e.g., "good first issue" + "documentation") pass through.
+ * Issues with no labels are not considered doc-only.
+ */
+export function isDocOnlyIssue(item) {
+    if (!item.labels || !Array.isArray(item.labels) || item.labels.length === 0)
+        return false;
+    const labelNames = item.labels.map((l) => (typeof l === 'string' ? l : l.name || '').toLowerCase());
+    // Filter out empty label names before checking
+    const nonEmptyLabels = labelNames.filter((n) => n.length > 0);
+    if (nonEmptyLabels.length === 0)
+        return false;
+    return nonEmptyLabels.every((n) => DOC_ONLY_LABELS.has(n));
+}
+/** Known beginner-type label names used to detect label-farming repos. */
+export const BEGINNER_LABELS = new Set([
+    'good first issue',
+    'hacktoberfest',
+    'easy',
+    'up-for-grabs',
+    'first-timers-only',
+    'beginner-friendly',
+    'beginner',
+    'starter',
+    'newbie',
+    'low-hanging-fruit',
+    'community',
+]);
+/** Check if a single issue has an excessive number of beginner labels (>= 5). */
+export function isLabelFarming(item) {
+    if (!item.labels || !Array.isArray(item.labels))
+        return false;
+    const labelNames = item.labels.map((l) => (typeof l === 'string' ? l : l.name || '').toLowerCase());
+    const beginnerCount = labelNames.filter((n) => BEGINNER_LABELS.has(n)).length;
+    return beginnerCount >= 5;
+}
+/** Detect mass-created issue titles like "Add Trivia Question 61" or "Create Entry #5". */
+export function hasTemplatedTitle(title) {
+    if (!title)
+        return false;
+    // Matches "<anything> <category-noun> <number>" where category nouns are typical
+    // of mass-created templated issues. This avoids false positives on legitimate titles
+    // like "Add support for Python 3" or "Implement RFC 7231" which lack category nouns.
+    return /^.+\s+(question|fact|point|item|task|entry|post|challenge|exercise|example|problem|tip|recipe|snippet)\s+#?\d+$/i.test(title);
+}
+/**
+ * Batch-analyze search items to detect label-farming repositories.
+ * Returns a Set of repo full names (owner/repo) that appear to be spam.
+ *
+ * A repo is flagged if:
+ * - ANY single issue has >= 5 beginner labels (strong individual signal), OR
+ * - It has >= 3 issues with templated titles (batch signal)
+ */
+export function detectLabelFarmingRepos(items) {
+    const spamRepos = new Set();
+    const repoSpamCounts = new Map();
+    for (const item of items) {
+        const repoFullName = item.repository_url.split('/').slice(-2).join('/');
+        // Strong signal: single issue with 5+ beginner labels
+        if (isLabelFarming(item)) {
+            spamRepos.add(repoFullName);
+            continue;
+        }
+        // Weaker signal: templated title
+        if (item.title && hasTemplatedTitle(item.title)) {
+            repoSpamCounts.set(repoFullName, (repoSpamCounts.get(repoFullName) || 0) + 1);
+        }
+    }
+    // Flag repos with 3+ templated-title issues
+    for (const [repo, count] of repoSpamCounts) {
+        if (count >= 3) {
+            spamRepos.add(repo);
+        }
+    }
+    return spamRepos;
+}
+/**
+ * Apply per-repo cap to candidates.
+ * Keeps at most `maxPerRepo` issues from any single repo.
+ * Maintains the existing sort order — first N from each repo are kept,
+ * excess issues from over-represented repos are dropped.
+ */
+export function applyPerRepoCap(candidates, maxPerRepo) {
+    const repoCounts = new Map();
+    const kept = [];
+    for (const c of candidates) {
+        const count = repoCounts.get(c.issue.repo) || 0;
+        if (count < maxPerRepo) {
+            kept.push(c);
+            repoCounts.set(c.issue.repo, count + 1);
+        }
+    }
+    return kept;
+}

package/dist/core/issue-scoring.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Issue Scoring — pure functions for computing viability scores and quality bonuses.
+ *
+ * Extracted from issue-discovery.ts to isolate scoring logic.
+ */
+/**
+ * Calculate a quality bonus based on repo star and fork counts.
+ * Stars: <50 -> 0, 50-499 -> +3, 500-4999 -> +5, 5000+ -> +8
+ * Forks: 50+ -> +2, 500+ -> +4
+ * Natural max is 12 (8 stars + 4 forks).
+ */
+export declare function calculateRepoQualityBonus(stargazersCount: number, forksCount: number): number;
+export interface ViabilityScoreParams {
+    repoScore: number | null;
+    hasExistingPR: boolean;
+    isClaimed: boolean;
+    clearRequirements: boolean;
+    hasContributionGuidelines: boolean;
+    issueUpdatedAt: string;
+    closedWithoutMergeCount: number;
+    mergedPRCount: number;
+    orgHasMergedPRs: boolean;
+    repoQualityBonus?: number;
+    /** True when the repo matches one of the user's preferred project categories. */
+    matchesPreferredCategory?: boolean;
+}
+/**
+ * Calculate viability score for an issue (0-100 scale)
+ * Scoring:
+ * - Base: 50 points
+ * - +repoScore*2 (up to +20 for score of 10)
+ * - +repoQualityBonus (up to +12 for established repos, from star/fork counts)
+ * - +15 for merged PR in this repo (direct proven relationship)
+ * - +15 for clear requirements (clarity)
+ * - +15 for freshness (recently updated)
+ * - +10 for contribution guidelines
+ * - +5 for org affinity (merged PRs in same org)
+ * - +5 for category preference (matches user's project categories)
+ * - -30 if existing PR
+ * - -20 if claimed
+ * - -15 if closed-without-merge history with no merges
+ */
+export declare function calculateViabilityScore(params: ViabilityScoreParams): number;

package/dist/core/issue-scoring.js

@@ -0,0 +1,97 @@
+/**
+ * Issue Scoring — pure functions for computing viability scores and quality bonuses.
+ *
+ * Extracted from issue-discovery.ts to isolate scoring logic.
+ */
+import { daysBetween } from './utils.js';
+/**
+ * Calculate a quality bonus based on repo star and fork counts.
+ * Stars: <50 -> 0, 50-499 -> +3, 500-4999 -> +5, 5000+ -> +8
+ * Forks: 50+ -> +2, 500+ -> +4
+ * Natural max is 12 (8 stars + 4 forks).
+ */
+export function calculateRepoQualityBonus(stargazersCount, forksCount) {
+    let bonus = 0;
+    // Star tiers
+    if (stargazersCount >= 5000)
+        bonus += 8;
+    else if (stargazersCount >= 500)
+        bonus += 5;
+    else if (stargazersCount >= 50)
+        bonus += 3;
+    // Fork tiers
+    if (forksCount >= 500)
+        bonus += 4;
+    else if (forksCount >= 50)
+        bonus += 2;
+    return bonus;
+}
+/**
+ * Calculate viability score for an issue (0-100 scale)
+ * Scoring:
+ * - Base: 50 points
+ * - +repoScore*2 (up to +20 for score of 10)
+ * - +repoQualityBonus (up to +12 for established repos, from star/fork counts)
+ * - +15 for merged PR in this repo (direct proven relationship)
+ * - +15 for clear requirements (clarity)
+ * - +15 for freshness (recently updated)
+ * - +10 for contribution guidelines
+ * - +5 for org affinity (merged PRs in same org)
+ * - +5 for category preference (matches user's project categories)
+ * - -30 if existing PR
+ * - -20 if claimed
+ * - -15 if closed-without-merge history with no merges
+ */
+export function calculateViabilityScore(params) {
+    let score = 50; // Base score
+    // Add repo score contribution (up to +20)
+    if (params.repoScore !== null) {
+        score += params.repoScore * 2;
+    }
+    // Repo quality bonus from star/fork counts (up to +12)
+    score += params.repoQualityBonus ?? 0;
+    // Merged PR bonus (+15) — direct proven relationship with this repo
+    if (params.mergedPRCount > 0) {
+        score += 15;
+    }
+    // Clarity bonus (+15)
+    if (params.clearRequirements) {
+        score += 15;
+    }
+    // Freshness bonus (+15 for issues updated within last 14 days)
+    const updatedAt = new Date(params.issueUpdatedAt);
+    const daysSinceUpdate = daysBetween(updatedAt);
+    if (daysSinceUpdate <= 14) {
+        score += 15;
+    }
+    else if (daysSinceUpdate <= 30) {
+        // Partial bonus for 15-30 days
+        score += Math.round(15 * (1 - (daysSinceUpdate - 14) / 16));
+    }
+    // Contribution guidelines bonus (+10)
+    if (params.hasContributionGuidelines) {
+        score += 10;
+    }
+    // Org affinity bonus (+5) — user has merged PRs in another repo under same org
+    if (params.orgHasMergedPRs) {
+        score += 5;
+    }
+    // Category preference bonus (+5) — repo matches user's preferred project categories
+    if (params.matchesPreferredCategory) {
+        score += 5;
+    }
+    // Penalty for existing PR (-30)
+    if (params.hasExistingPR) {
+        score -= 30;
+    }
+    // Penalty for claimed issue (-20)
+    if (params.isClaimed) {
+        score -= 20;
+    }
+    // Penalty for closed-without-merge history with no successful merges (-15)
+    if (params.closedWithoutMergeCount > 0 && params.mergedPRCount === 0) {
+        score -= 15;
+    }
+    // Clamp to 0-100
+    return Math.max(0, Math.min(100, score));
+}

package/dist/core/issue-vetting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Issue Vetting — orchestrates individual issue checks and computes
+ * recommendation + viability score.
+ *
+ * Delegates to focused modules:
+ * - issue-eligibility.ts — PR existence, claim detection, requirements analysis
+ * - repo-health.ts       — project health, contribution guidelines
+ */
+import { Octokit } from '@octokit/rest';
+import { type SearchPriority, type IssueCandidate, type ProjectCategory } from './types.js';
+/**
+ * Read-only interface for accessing scout state during issue vetting.
+ * Implementations may be backed by gist persistence, in-memory state, etc.
+ */
+export interface ScoutStateReader {
+    /** Repos where the user has at least one merged PR. */
+    getReposWithMergedPRs(): string[];
+    /** User's starred repos (from GitHub). */
+    getStarredRepos(): string[];
+    /** Preferred GitHub orgs from user preferences. */
+    getPreferredOrgs(): string[];
+    /** Preferred project categories from user preferences. */
+    getProjectCategories(): ProjectCategory[];
+    /** Numeric quality score for a repo, or null if not evaluated. */
+    getRepoScore(repo: string): number | null;
+}
+export declare class IssueVetter {
+    private octokit;
+    private stateReader;
+    constructor(octokit: Octokit, stateReader: ScoutStateReader);
+    /**
+     * Vet a specific issue — runs all checks and computes recommendation + viability score.
+     * Results are cached for 15 minutes to avoid redundant API calls on repeated searches.
+     */
+    vetIssue(issueUrl: string): Promise<IssueCandidate>;
+    /**
+     * Vet multiple issues in parallel with concurrency limit
+     */
+    vetIssuesParallel(urls: string[], maxResults: number, priority?: SearchPriority): Promise<{
+        candidates: IssueCandidate[];
+        allFailed: boolean;
+        rateLimitHit: boolean;
+    }>;
+}

package/dist/core/issue-vetting.js

@@ -0,0 +1,270 @@
+/**
+ * Issue Vetting — orchestrates individual issue checks and computes
+ * recommendation + viability score.
+ *
+ * Delegates to focused modules:
+ * - issue-eligibility.ts — PR existence, claim detection, requirements analysis
+ * - repo-health.ts       — project health, contribution guidelines
+ */
+import { parseGitHubUrl } from './utils.js';
+import { ValidationError, errorMessage, isRateLimitError } from './errors.js';
+import { debug, warn } from './logger.js';
+import { calculateRepoQualityBonus, calculateViabilityScore } from './issue-scoring.js';
+import { repoBelongsToCategory } from './category-mapping.js';
+import { checkNoExistingPR, checkNotClaimed, checkUserMergedPRsInRepo, analyzeRequirements, } from './issue-eligibility.js';
+import { checkProjectHealth, fetchContributionGuidelines } from './repo-health.js';
+import { getHttpCache } from './http-cache.js';
+const MODULE = 'issue-vetting';
+/** Vetting concurrency: kept low to reduce burst pressure on GitHub's secondary rate limit. */
+const MAX_CONCURRENT_VETTING = 3;
+/** TTL for cached vetting results (15 minutes). Kept short so config changes take effect quickly. */
+const VETTING_CACHE_TTL_MS = 15 * 60 * 1000;
+export class IssueVetter {
+    octokit;
+    stateReader;
+    constructor(octokit, stateReader) {
+        this.octokit = octokit;
+        this.stateReader = stateReader;
+    }
+    /**
+     * Vet a specific issue — runs all checks and computes recommendation + viability score.
+     * Results are cached for 15 minutes to avoid redundant API calls on repeated searches.
+     */
+    async vetIssue(issueUrl) {
+        // Check vetting cache first — avoids ~6+ API calls per issue
+        const cache = getHttpCache();
+        const cacheKey = `vet:${issueUrl}`;
+        const cached = cache.getIfFresh(cacheKey, VETTING_CACHE_TTL_MS);
+        if (cached && typeof cached === 'object' && 'issue' in cached && 'viabilityScore' in cached) {
+            debug(MODULE, `Vetting cache hit for ${issueUrl}`);
+            return cached;
+        }
+        // Parse URL
+        const parsed = parseGitHubUrl(issueUrl);
+        if (!parsed || parsed.type !== 'issues') {
+            throw new ValidationError(`Invalid issue URL: ${issueUrl}`);
+        }
+        const { owner, repo, number } = parsed;
+        const repoFullName = `${owner}/${repo}`;
+        // Fetch issue data
+        const { data: ghIssue } = await this.octokit.issues.get({
+            owner,
+            repo,
+            issue_number: number,
+        });
+        // Check if the user already has merged PRs in this repo (skip the Search API call)
+        const reposWithMergedPRs = this.stateReader.getReposWithMergedPRs();
+        const hasMergedPRsInRepo = reposWithMergedPRs.includes(repoFullName);
+        // Run all vetting checks in parallel — delegates to standalone functions
+        const [existingPRCheck, claimCheck, projectHealth, contributionGuidelines, userMergedPRCount] = await Promise.all([
+            checkNoExistingPR(this.octokit, owner, repo, number),
+            checkNotClaimed(this.octokit, owner, repo, number, ghIssue.comments),
+            checkProjectHealth(this.octokit, owner, repo),
+            fetchContributionGuidelines(this.octokit, owner, repo),
+            hasMergedPRsInRepo ? Promise.resolve(0) : checkUserMergedPRsInRepo(this.octokit, owner, repo),
+        ]);
+        const noExistingPR = existingPRCheck.passed;
+        const notClaimed = claimCheck.passed;
+        // Analyze issue quality
+        const clearRequirements = analyzeRequirements(ghIssue.body || '');
+        // When the health check itself failed (API error), use a neutral default:
+        // don't penalize the repo as inactive, but don't credit it as active either.
+        const projectActive = projectHealth.checkFailed ? true : projectHealth.isActive;
+        const vettingResult = {
+            passedAllChecks: noExistingPR && notClaimed && projectActive && clearRequirements,
+            checks: {
+                noExistingPR,
+                notClaimed,
+                projectActive,
+                clearRequirements,
+                contributionGuidelinesFound: !!contributionGuidelines,
+            },
+            contributionGuidelines,
+            notes: [],
+        };
+        // Build notes
+        if (!noExistingPR)
+            vettingResult.notes.push('Existing PR found for this issue');
+        if (!notClaimed)
+            vettingResult.notes.push('Issue appears to be claimed by someone');
+        if (existingPRCheck.inconclusive) {
+            vettingResult.notes.push(`Could not verify absence of existing PRs: ${existingPRCheck.reason || 'API error'}`);
+        }
+        if (claimCheck.inconclusive) {
+            vettingResult.notes.push(`Could not verify claim status: ${claimCheck.reason || 'API error'}`);
+        }
+        if (projectHealth.checkFailed) {
+            vettingResult.notes.push(`Could not verify project activity: ${projectHealth.failureReason || 'API error'}`);
+        }
+        else if (!projectHealth.isActive) {
+            vettingResult.notes.push('Project may be inactive');
+        }
+        if (!clearRequirements)
+            vettingResult.notes.push('Issue requirements are unclear');
+        if (!contributionGuidelines)
+            vettingResult.notes.push('No CONTRIBUTING.md found');
+        // Create tracked issue
+        const trackedIssue = {
+            id: ghIssue.id,
+            url: issueUrl,
+            repo: repoFullName,
+            number,
+            title: ghIssue.title,
+            status: 'candidate',
+            labels: ghIssue.labels.map((l) => (typeof l === 'string' ? l : l.name || '')),
+            createdAt: ghIssue.created_at,
+            updatedAt: ghIssue.updated_at,
+            vetted: true,
+            vettingResult,
+        };
+        // Determine recommendation
+        const reasonsToSkip = [];
+        const reasonsToApprove = [];
+        if (!noExistingPR)
+            reasonsToSkip.push('Has existing PR');
+        if (!notClaimed)
+            reasonsToSkip.push('Already claimed');
+        if (!projectHealth.isActive && !projectHealth.checkFailed)
+            reasonsToSkip.push('Inactive project');
+        if (!clearRequirements)
+            reasonsToSkip.push('Unclear requirements');
+        if (noExistingPR)
+            reasonsToApprove.push('No existing PR');
+        if (notClaimed)
+            reasonsToApprove.push('Not claimed');
+        if (projectHealth.isActive && !projectHealth.checkFailed)
+            reasonsToApprove.push('Active project');
+        if (clearRequirements)
+            reasonsToApprove.push('Clear requirements');
+        if (contributionGuidelines)
+            reasonsToApprove.push('Has contribution guidelines');
+        // Determine effective merged PR count: prefer local state (authoritative if present),
+        // fall back to live GitHub API count to detect contributions made before using oss-scout
+        const effectiveMergedCount = hasMergedPRsInRepo ? 1 : userMergedPRCount;
+        if (effectiveMergedCount > 0) {
+            reasonsToApprove.push(`Trusted project (${effectiveMergedCount} PR${effectiveMergedCount > 1 ? 's' : ''} merged)`);
+        }
+        // Check for org-level affinity (user has merged PRs in another repo under same org)
+        const orgName = repoFullName.split('/')[0];
+        let orgHasMergedPRs = false;
+        if (orgName && repoFullName.includes('/')) {
+            orgHasMergedPRs = reposWithMergedPRs.some((r) => r.startsWith(orgName + '/') && r !== repoFullName);
+        }
+        if (orgHasMergedPRs) {
+            reasonsToApprove.push(`Org affinity (merged PRs in other ${orgName} repos)`);
+        }
+        // Check for category preference match
+        const projectCategories = this.stateReader.getProjectCategories();
+        const matchesCategory = repoBelongsToCategory(repoFullName, projectCategories);
+        if (matchesCategory) {
+            reasonsToApprove.push('Matches preferred project category');
+        }
+        let recommendation;
+        if (vettingResult.passedAllChecks) {
+            recommendation = 'approve';
+        }
+        else if (reasonsToSkip.length > 2) {
+            recommendation = 'skip';
+        }
+        else {
+            recommendation = 'needs_review';
+        }
+        // Downgrade to needs_review if any check was inconclusive —
+        // "approve" should only be given when all checks actually passed, not when they were skipped.
+        const hasInconclusiveChecks = projectHealth.checkFailed || existingPRCheck.inconclusive || claimCheck.inconclusive;
+        if (recommendation === 'approve' && hasInconclusiveChecks) {
+            recommendation = 'needs_review';
+            vettingResult.notes.push('Recommendation downgraded: one or more checks were inconclusive');
+        }
+        // Calculate repo quality bonus from star/fork counts
+        const repoQualityBonus = calculateRepoQualityBonus(projectHealth.stargazersCount ?? 0, projectHealth.forksCount ?? 0);
+        if (projectHealth.checkFailed && repoQualityBonus === 0) {
+            vettingResult.notes.push('Repo quality bonus unavailable: could not fetch star/fork counts due to API error');
+        }
+        const repoScore = this.stateReader.getRepoScore(repoFullName);
+        const viabilityScore = calculateViabilityScore({
+            repoScore,
+            hasExistingPR: !noExistingPR,
+            isClaimed: !notClaimed,
+            clearRequirements,
+            hasContributionGuidelines: !!contributionGuidelines,
+            issueUpdatedAt: ghIssue.updated_at,
+            closedWithoutMergeCount: 0,
+            mergedPRCount: effectiveMergedCount,
+            orgHasMergedPRs,
+            repoQualityBonus,
+            matchesPreferredCategory: matchesCategory,
+        });
+        const starredRepos = this.stateReader.getStarredRepos();
+        const preferredOrgs = this.stateReader.getPreferredOrgs();
+        let searchPriority = 'normal';
+        if (effectiveMergedCount > 0) {
+            searchPriority = 'merged_pr';
+        }
+        else if (preferredOrgs.some((o) => o.toLowerCase() === orgName?.toLowerCase())) {
+            searchPriority = 'preferred_org';
+        }
+        else if (starredRepos.includes(repoFullName)) {
+            searchPriority = 'starred';
+        }
+        const result = {
+            issue: trackedIssue,
+            vettingResult,
+            projectHealth,
+            recommendation,
+            reasonsToSkip,
+            reasonsToApprove,
+            viabilityScore,
+            searchPriority,
+        };
+        // Cache the vetting result to avoid redundant API calls on repeated searches
+        cache.set(cacheKey, '', result);
+        return result;
+    }
+    /**
+     * Vet multiple issues in parallel with concurrency limit
+     */
+    async vetIssuesParallel(urls, maxResults, priority) {
+        const candidates = [];
+        const pending = new Map();
+        let failedVettingCount = 0;
+        let rateLimitFailures = 0;
+        let attemptedCount = 0;
+        for (const url of urls) {
+            if (candidates.length >= maxResults)
+                break;
+            attemptedCount++;
+            const task = this.vetIssue(url)
+                .then((candidate) => {
+                if (candidates.length < maxResults) {
+                    // Override the priority if provided
+                    if (priority) {
+                        candidate.searchPriority = priority;
+                    }
+                    candidates.push(candidate);
+                }
+            })
+                .catch((error) => {
+                failedVettingCount++;
+                if (isRateLimitError(error)) {
+                    rateLimitFailures++;
+                }
+                warn(MODULE, `Error vetting issue ${url}:`, errorMessage(error));
+            })
+                .finally(() => pending.delete(url));
+            pending.set(url, task);
+            // Limit concurrency — wait for at least one to complete before launching more
+            if (pending.size >= MAX_CONCURRENT_VETTING) {
+                await Promise.race(pending.values());
+            }
+        }
+        // Wait for remaining
+        await Promise.allSettled(pending.values());
+        const allFailed = failedVettingCount === attemptedCount && attemptedCount > 0;
+        if (allFailed) {
+            warn(MODULE, `All ${attemptedCount} issue(s) failed vetting. ` +
+                `This may indicate a systemic issue (rate limit, auth, network).`);
+        }
+        return { candidates: candidates.slice(0, maxResults), allFailed, rateLimitHit: rateLimitFailures > 0 };
+    }
+}

package/dist/core/local-state.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Local state persistence — reads/writes ScoutState to ~/.oss-scout/state.json.
+ */
+import type { ScoutState } from './schemas.js';
+/**
+ * Check if a local state file exists.
+ */
+export declare function hasLocalState(): boolean;
+/**
+ * Load state from local file. Returns fresh default state if file doesn't exist or is corrupt.
+ */
+export declare function loadLocalState(): ScoutState;
+/**
+ * Save state to local file using atomic write (write to .tmp, then rename).
+ */
+export declare function saveLocalState(state: ScoutState): void;

package/dist/core/local-state.js

@@ -0,0 +1,56 @@
+/**
+ * Local state persistence — reads/writes ScoutState to ~/.oss-scout/state.json.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ScoutStateSchema } from './schemas.js';
+import { getDataDir } from './utils.js';
+import { debug, warn } from './logger.js';
+import { errorMessage } from './errors.js';
+const MODULE = 'local-state';
+function getStatePath() {
+    return path.join(getDataDir(), 'state.json');
+}
+/**
+ * Check if a local state file exists.
+ */
+export function hasLocalState() {
+    return fs.existsSync(getStatePath());
+}
+/**
+ * Load state from local file. Returns fresh default state if file doesn't exist or is corrupt.
+ */
+export function loadLocalState() {
+    const statePath = getStatePath();
+    try {
+        const raw = fs.readFileSync(statePath, 'utf-8');
+        return ScoutStateSchema.parse(JSON.parse(raw));
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT') {
+            return ScoutStateSchema.parse({ version: 1 });
+        }
+        // State file exists but is corrupt or unreadable
+        warn(MODULE, `Failed to load state from ${statePath}: ${errorMessage(err)}. Using defaults.`);
+        // Backup corrupt file
+        try {
+            const backupPath = `${statePath}.corrupt.${Date.now()}`;
+            fs.copyFileSync(statePath, backupPath);
+            warn(MODULE, `Corrupt state backed up to ${backupPath}`);
+        }
+        catch { /* best effort backup */ }
+        return ScoutStateSchema.parse({ version: 1 });
+    }
+}
+/**
+ * Save state to local file using atomic write (write to .tmp, then rename).
+ */
+export function saveLocalState(state) {
+    const statePath = getStatePath();
+    const tmpPath = statePath + '.tmp';
+    const data = JSON.stringify(state, null, 2) + '\n';
+    fs.writeFileSync(tmpPath, data, { mode: 0o600 });
+    fs.renameSync(tmpPath, statePath);
+    debug(MODULE, 'State saved');
+}