@oss-scout/core 0.7.1 → 0.9.0

package/dist/scout.js

@@ -5,12 +5,30 @@
  * Implements ScoutStateReader to bridge state with the search engine.
  */
 import { IssueDiscovery } from "./core/issue-discovery.js";
+import { IssueVetter } from "./core/issue-vetting.js";
+import { discoverFeatures, discoverFeaturesBroad, } from "./core/feature-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";
 import { extractRepoFromUrl } from "./core/utils.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError, } from "./core/errors.js";
+/** Cause-specific user-facing message for degraded (offline) mode. */
+function offlineModeMessage(reason) {
+    const tail = "Changes will only be saved locally.";
+    switch (reason) {
+        case "rate_limit":
+            return `Gist sync unavailable — GitHub API rate limit exceeded. ${tail} Try again after the rate limit resets.`;
+        case "network":
+            return `Gist sync unavailable — could not reach GitHub. ${tail} Check your network connection.`;
+        case "server":
+            return `Gist sync unavailable — GitHub returned a server error. ${tail} Try again later.`;
+        case "unknown":
+        case undefined:
+            return `Gist sync unavailable — running in offline mode. ${tail}`;
+    }
+}
 /** Wrap a real Octokit instance as GistOctokitLike without unsafe double casts. */
 function toGistOctokit(octokit) {
     return {
@@ -84,7 +102,7 @@ export async function createScout(config) {
         gistStore = new GistStateStore(toGistOctokit(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.");
+            warn("scout", offlineModeMessage(result.degradedReason));
         }
         const localState = loadLocalState();
         state = mergeStates(localState, result.state);
@@ -148,6 +166,48 @@ export class OssScout {
         const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
         return discovery.vetIssue(issueUrl);
     }
+    /**
+     * `scout features` — surfaces feature-scoped contribution opportunities
+     * in repos where the user has 3+ merged PRs (configurable via
+     * `featuresAnchorThreshold`), ranked into separate "quick wins" and
+     * "bigger bets" buckets (split via `featuresSplitRatio`).
+     *
+     * Per-call `anchorThreshold` and `splitRatio` overrides take precedence
+     * over the persisted preferences.
+     *
+     * When `broad` is true (#100), bypasses anchor resolution and runs a
+     * cross-repo GitHub Search query for first-touch contributors who
+     * haven't yet built repo relationships. Filters by user language
+     * preferences and excluded repos/orgs.
+     */
+    async features(options) {
+        const count = options?.count ?? 10;
+        const octokit = getOctokit(this.githubToken);
+        const vetter = new IssueVetter(octokit, this);
+        const result = options?.broad
+            ? await discoverFeaturesBroad({
+                octokit,
+                vetter,
+                count,
+                languages: this.state.preferences.languages,
+                excludeRepos: this.state.preferences.excludeRepos,
+                excludeOrgs: this.state.preferences.excludeOrgs,
+                splitRatio: options?.splitRatio ?? this.state.preferences.featuresSplitRatio,
+            })
+            : await discoverFeatures({
+                octokit,
+                vetter,
+                repoScores: this.state.repoScores ?? {},
+                count,
+                anchorThreshold: options?.anchorThreshold ??
+                    this.state.preferences.featuresAnchorThreshold,
+                splitRatio: options?.splitRatio ?? this.state.preferences.featuresSplitRatio,
+            });
+        this.saveResults([...result.quickWins, ...result.biggerBets]);
+        this.state.lastSearchAt = new Date().toISOString();
+        this.dirty = true;
+        return result;
+    }
     // ── Batch Vetting ───────────────────────────────────────────────────
     /**
      * Re-vet all saved results with bounded concurrency.
@@ -159,7 +219,15 @@ export class OssScout {
         const concurrency = options?.concurrency ?? 5;
         const results = [];
         const pending = new Map();
+        // First 401 OR rate-limit short-circuits the whole batch. Unlike
+        // vetIssuesParallel (which has a batch-level rateLimitHit flag the
+        // search orchestrator surfaces via rateLimitWarning), vetList is the
+        // user-facing CLI entry point — N rows of "rate limit exceeded" is the
+        // exact silent-failure mode the documented strategy aims to prevent.
+        let firstHardError = null;
         for (const item of saved) {
+            if (firstHardError)
+                break;
             const task = this.vetIssue(item.issueUrl)
                 .then((candidate) => {
                 results.push({
@@ -173,15 +241,19 @@ export class OssScout {
                 });
             })
                 .catch((error) => {
-                const msg = error instanceof Error ? error.message : String(error);
-                const isGone = msg.includes("Not Found") || msg.includes("410");
+                if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
+                    firstHardError ??= error;
+                    return;
+                }
+                const status = getHttpStatusCode(error);
+                const isGone = status === 404 || status === 410;
                 results.push({
                     issueUrl: item.issueUrl,
                     repo: item.repo,
                     number: item.number,
                     title: item.title,
                     status: isGone ? "closed" : "error",
-                    errorMessage: msg,
+                    errorMessage: errorMessage(error),
                 });
             })
                 .finally(() => {
@@ -193,6 +265,12 @@ export class OssScout {
             }
         }
         await Promise.allSettled(pending.values());
+        if (firstHardError) {
+            if (results.length > 0) {
+                warn("scout", `vetList aborted mid-batch after ${results.length} result(s) — discarding partial results due to auth/rate-limit failure`);
+            }
+            throw firstHardError;
+        }
         const summary = {
             total: results.length,
             stillAvailable: results.filter((r) => r.status === "still_available")
@@ -389,6 +467,7 @@ export class OssScout {
                 firstSeenAt: prev?.firstSeenAt ?? now,
                 lastSeenAt: now,
                 lastScore: c.viabilityScore,
+                horizon: "horizon" in c ? c.horizon : undefined,
             });
         }
         this.state.savedResults = [...existing.values()];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.7.1",
+  "version": "0.9.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": {