@oss-scout/core 0.2.0 → 0.2.1

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

@@ -5,8 +5,8 @@
  *
  * Extracted from issue-vetting.ts to isolate eligibility logic.
  */
-import { Octokit } from '@octokit/rest';
-import type { CheckResult } from './types.js';
+import { Octokit } from "@octokit/rest";
+import type { CheckResult } from "./types.js";
 /**
  * Check whether an open PR already exists for the given issue.
  * Uses the timeline API (REST) to detect cross-referenced PRs, avoiding

package/dist/core/issue-eligibility.js

@@ -5,29 +5,29 @@
  *
  * Extracted from issue-vetting.ts to isolate eligibility logic.
  */
-import { paginateAll } from './pagination.js';
-import { errorMessage } from './errors.js';
-import { warn } from './logger.js';
-import { getHttpCache } from './http-cache.js';
-import { getSearchBudgetTracker } from './search-budget.js';
-const MODULE = 'issue-eligibility';
+import { paginateAll } from "./pagination.js";
+import { errorMessage } from "./errors.js";
+import { warn } from "./logger.js";
+import { getHttpCache } from "./http-cache.js";
+import { getSearchBudgetTracker } from "./search-budget.js";
+const MODULE = "issue-eligibility";
 /** Phrases that indicate someone has already claimed an issue. */
 const CLAIM_PHRASES = [
     "i'm working on this",
-    'i am working on this',
+    "i am working on this",
     "i'll take this",
-    'i will take this',
-    'working on it',
+    "i will take this",
+    "working on it",
     "i'd like to work on",
-    'i would like to work on',
-    'can i work on',
-    'may i work on',
-    'assigned to me',
+    "i would like to work on",
+    "can i work on",
+    "may i work on",
+    "assigned to me",
     "i'm on it",
     "i'll submit a pr",
-    'i will submit a pr',
-    'working on a fix',
-    'working on a pr',
+    "i will submit a pr",
+    "working on a fix",
+    "working on a pr",
 ];
 /**
  * Check whether an open PR already exists for the given issue.
@@ -50,7 +50,7 @@ export async function checkNoExistingPR(octokit, owner, repo, issueNumber) {
         }));
         const linkedPRs = timeline.filter((event) => {
             const e = event;
-            return e.event === 'cross-referenced' && e.source?.issue?.pull_request;
+            return e.event === "cross-referenced" && e.source?.issue?.pull_request;
         });
         return { passed: linkedPRs.length === 0 };
     }
@@ -75,7 +75,7 @@ export async function checkUserMergedPRsInRepo(octokit, owner, repo) {
     // error-path fallback values (a transient failure returning 0 would poison the
     // cache for 15 minutes, hiding that the user has merged PRs in the repo).
     const cached = cache.getIfFresh(cacheKey, MERGED_PR_CACHE_TTL_MS);
-    if (cached != null && typeof cached === 'number') {
+    if (cached != null && typeof cached === "number") {
         return cached;
     }
     try {
@@ -88,7 +88,7 @@ export async function checkUserMergedPRsInRepo(octokit, owner, repo) {
                 per_page: 1, // We only need total_count
             });
             // Only cache successful results
-            cache.set(cacheKey, '', data.total_count);
+            cache.set(cacheKey, "", data.total_count);
             return data.total_count;
         }
         finally {
@@ -120,7 +120,7 @@ export async function checkNotClaimed(octokit, owner, repo, issueNumber, comment
         // Limit to last 100 comments to avoid excessive processing
         const recentComments = comments.slice(-100);
         for (const comment of recentComments) {
-            const body = (comment.body || '').toLowerCase();
+            const body = (comment.body || "").toLowerCase();
             if (CLAIM_PHRASES.some((phrase) => body.includes(phrase))) {
                 return { passed: false };
             }
@@ -146,6 +146,11 @@ export function analyzeRequirements(body) {
     const hasCodeBlock = /```/.test(body);
     const hasExpectedBehavior = /expect|should|must|want/i.test(body);
     // Must have at least two indicators of clarity
-    const indicators = [hasSteps, hasCodeBlock, hasExpectedBehavior, body.length > 200];
+    const indicators = [
+        hasSteps,
+        hasCodeBlock,
+        hasExpectedBehavior,
+        body.length > 200,
+    ];
     return indicators.filter(Boolean).length >= 2;
 }

package/dist/core/issue-filtering.js

@@ -4,8 +4,14 @@
  * Extracted from issue-discovery.ts to isolate filtering logic:
  * label farming detection, doc-only filtering, per-repo caps, templated title detection.
  */
+import { extractRepoFromUrl } from "./utils.js";
 /** Labels that indicate documentation-only issues. */
-export const DOC_ONLY_LABELS = new Set(['documentation', 'docs', 'typo', 'spelling']);
+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.
@@ -14,7 +20,7 @@ export const DOC_ONLY_LABELS = new Set(['documentation', 'docs', 'typo', 'spelli
 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());
+    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)
@@ -23,23 +29,23 @@ export function isDocOnlyIssue(item) {
 }
 /** 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',
+    "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 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;
 }
@@ -64,7 +70,9 @@ 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('/');
+        const repoFullName = extractRepoFromUrl(item.repository_url);
+        if (!repoFullName)
+            continue;
         // Strong signal: single issue with 5+ beginner labels
         if (isLabelFarming(item)) {
             spamRepos.add(repoFullName);

package/dist/core/issue-scoring.js

@@ -3,7 +3,7 @@
  *
  * Extracted from issue-discovery.ts to isolate scoring logic.
  */
-import { daysBetween } from './utils.js';
+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

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

@@ -6,8 +6,8 @@
  * - 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';
+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.

package/dist/core/issue-vetting.js

@@ -6,15 +6,15 @@
  * - 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';
+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. */
@@ -35,13 +35,16 @@ export class IssueVetter {
         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) {
+        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') {
+        if (!parsed || parsed.type !== "issues") {
             throw new ValidationError(`Invalid issue URL: ${issueUrl}`);
         }
         const { owner, repo, number } = parsed;
@@ -56,20 +59,24 @@ export class IssueVetter {
         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([
+        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),
+            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 || '');
+        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 projectActive = projectHealth.checkFailed
+            ? true
+            : projectHealth.isActive;
         const vettingResult = {
             passedAllChecks: noExistingPR && notClaimed && projectActive && clearRequirements,
             checks: {
@@ -84,25 +91,25 @@ export class IssueVetter {
         };
         // Build notes
         if (!noExistingPR)
-            vettingResult.notes.push('Existing PR found for this issue');
+            vettingResult.notes.push("Existing PR found for this issue");
         if (!notClaimed)
-            vettingResult.notes.push('Issue appears to be claimed by someone');
+            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'}`);
+            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'}`);
+            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'}`);
+            vettingResult.notes.push(`Could not verify project activity: ${projectHealth.failureReason || "API error"}`);
         }
         else if (!projectHealth.isActive) {
-            vettingResult.notes.push('Project may be inactive');
+            vettingResult.notes.push("Project may be inactive");
         }
         if (!clearRequirements)
-            vettingResult.notes.push('Issue requirements are unclear');
+            vettingResult.notes.push("Issue requirements are unclear");
         if (!contributionGuidelines)
-            vettingResult.notes.push('No CONTRIBUTING.md found');
+            vettingResult.notes.push("No CONTRIBUTING.md found");
         // Create tracked issue
         const trackedIssue = {
             id: ghIssue.id,
@@ -110,8 +117,8 @@ export class IssueVetter {
             repo: repoFullName,
             number,
             title: ghIssue.title,
-            status: 'candidate',
-            labels: ghIssue.labels.map((l) => (typeof l === 'string' ? l : l.name || '')),
+            status: "candidate",
+            labels: ghIssue.labels.map((l) => typeof l === "string" ? l : l.name || ""),
             createdAt: ghIssue.created_at,
             updatedAt: ghIssue.updated_at,
             vetted: true,
@@ -121,34 +128,34 @@ export class IssueVetter {
         const reasonsToSkip = [];
         const reasonsToApprove = [];
         if (!noExistingPR)
-            reasonsToSkip.push('Has existing PR');
+            reasonsToSkip.push("Has existing PR");
         if (!notClaimed)
-            reasonsToSkip.push('Already claimed');
+            reasonsToSkip.push("Already claimed");
         if (!projectHealth.isActive && !projectHealth.checkFailed)
-            reasonsToSkip.push('Inactive project');
+            reasonsToSkip.push("Inactive project");
         if (!clearRequirements)
-            reasonsToSkip.push('Unclear requirements');
+            reasonsToSkip.push("Unclear requirements");
         if (noExistingPR)
-            reasonsToApprove.push('No existing PR');
+            reasonsToApprove.push("No existing PR");
         if (notClaimed)
-            reasonsToApprove.push('Not claimed');
+            reasonsToApprove.push("Not claimed");
         if (projectHealth.isActive && !projectHealth.checkFailed)
-            reasonsToApprove.push('Active project');
+            reasonsToApprove.push("Active project");
         if (clearRequirements)
-            reasonsToApprove.push('Clear requirements');
+            reasonsToApprove.push("Clear requirements");
         if (contributionGuidelines)
-            reasonsToApprove.push('Has contribution guidelines');
+            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)`);
+            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];
+        const orgName = repoFullName.split("/")[0];
         let orgHasMergedPRs = false;
-        if (orgName && repoFullName.includes('/')) {
-            orgHasMergedPRs = reposWithMergedPRs.some((r) => r.startsWith(orgName + '/') && r !== repoFullName);
+        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)`);
@@ -157,29 +164,31 @@ export class IssueVetter {
         const projectCategories = this.stateReader.getProjectCategories();
         const matchesCategory = repoBelongsToCategory(repoFullName, projectCategories);
         if (matchesCategory) {
-            reasonsToApprove.push('Matches preferred project category');
+            reasonsToApprove.push("Matches preferred project category");
         }
         let recommendation;
         if (vettingResult.passedAllChecks) {
-            recommendation = 'approve';
+            recommendation = "approve";
         }
         else if (reasonsToSkip.length > 2) {
-            recommendation = 'skip';
+            recommendation = "skip";
         }
         else {
-            recommendation = 'needs_review';
+            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');
+        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');
+            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({
@@ -197,15 +206,15 @@ export class IssueVetter {
         });
         const starredRepos = this.stateReader.getStarredRepos();
         const preferredOrgs = this.stateReader.getPreferredOrgs();
-        let searchPriority = 'normal';
+        let searchPriority = "normal";
         if (effectiveMergedCount > 0) {
-            searchPriority = 'merged_pr';
+            searchPriority = "merged_pr";
         }
         else if (preferredOrgs.some((o) => o.toLowerCase() === orgName?.toLowerCase())) {
-            searchPriority = 'preferred_org';
+            searchPriority = "preferred_org";
         }
         else if (starredRepos.includes(repoFullName)) {
-            searchPriority = 'starred';
+            searchPriority = "starred";
         }
         const result = {
             issue: trackedIssue,
@@ -218,7 +227,7 @@ export class IssueVetter {
             searchPriority,
         };
         // Cache the vetting result to avoid redundant API calls on repeated searches
-        cache.set(cacheKey, '', result);
+        cache.set(cacheKey, "", result);
         return result;
     }
     /**
@@ -265,6 +274,10 @@ export class IssueVetter {
             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 };
+        return {
+            candidates: candidates.slice(0, maxResults),
+            allFailed,
+            rateLimitHit: rateLimitFailures > 0,
+        };
     }
 }

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

@@ -1,7 +1,7 @@
 /**
  * Local state persistence — reads/writes ScoutState to ~/.oss-scout/state.json.
  */
-import type { ScoutState } from './schemas.js';
+import type { ScoutState } from "./schemas.js";
 /**
  * Check if a local state file exists.
  */

package/dist/core/local-state.js

@@ -1,15 +1,15 @@
 /**
  * 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';
+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');
+    return path.join(getDataDir(), "state.json");
 }
 /**
  * Check if a local state file exists.
@@ -23,12 +23,12 @@ export function hasLocalState() {
 export function loadLocalState() {
     const statePath = getStatePath();
     try {
-        const raw = fs.readFileSync(statePath, 'utf-8');
+        const raw = fs.readFileSync(statePath, "utf-8");
         return ScoutStateSchema.parse(JSON.parse(raw));
     }
     catch (err) {
         const code = err?.code;
-        if (code === 'ENOENT') {
+        if (code === "ENOENT") {
             return ScoutStateSchema.parse({ version: 1 });
         }
         // State file exists but is corrupt or unreadable
@@ -39,7 +39,9 @@ export function loadLocalState() {
             fs.copyFileSync(statePath, backupPath);
             warn(MODULE, `Corrupt state backed up to ${backupPath}`);
         }
-        catch { /* best effort backup */ }
+        catch {
+            /* best effort backup */
+        }
         return ScoutStateSchema.parse({ version: 1 });
     }
 }
@@ -48,9 +50,9 @@ export function loadLocalState() {
  */
 export function saveLocalState(state) {
     const statePath = getStatePath();
-    const tmpPath = statePath + '.tmp';
-    const data = JSON.stringify(state, null, 2) + '\n';
+    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');
+    debug(MODULE, "State saved");
 }

package/dist/core/repo-health.d.ts

@@ -4,8 +4,8 @@
  * Extracted from issue-vetting.ts to isolate repo-level checks
  * from issue-level eligibility logic.
  */
-import { Octokit } from '@octokit/rest';
-import { type ContributionGuidelines, type ProjectHealth } from './types.js';
+import { Octokit } from "@octokit/rest";
+import { type ContributionGuidelines, type ProjectHealth } from "./types.js";
 /**
  * Check the health of a GitHub project: recent commits, CI status, star/fork counts.
  * Results are cached for HEALTH_CACHE_TTL_MS (4 hours).