@oss-scout/core 0.7.1 → 0.9.0

package/dist/core/issue-vetting.js

@@ -7,7 +7,7 @@
  * - repo-health.ts       — project health, contribution guidelines
  */
 import { parseGitHubUrl } from "./utils.js";
-import { ValidationError, errorMessage, isRateLimitError } from "./errors.js";
+import { ValidationError, errorMessage, getHttpStatusCode, isRateLimitError, } from "./errors.js";
 import { debug, warn } from "./logger.js";
 import { calculateRepoQualityBonus, calculateViabilityScore, } from "./issue-scoring.js";
 import { repoBelongsToCategory } from "./category-mapping.js";
@@ -31,11 +31,19 @@ export class IssueVetter {
     /**
      * 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.
+     *
+     * `opts.featureSignals` are forwarded directly to scoring; the vetter does
+     * not derive them from the fetched issue. Cache key includes a digest of
+     * the signals so the same URL with different signals doesn't return a
+     * stale score.
      */
-    async vetIssue(issueUrl) {
+    async vetIssue(issueUrl, opts) {
         // Check vetting cache first — avoids ~6+ API calls per issue
         const cache = getHttpCache();
-        const cacheKey = `vet:${issueUrl}`;
+        const sigKey = opts?.featureSignals
+            ? `:r${opts.featureSignals.reactions}c${opts.featureSignals.comments}m${opts.featureSignals.hasMilestone ? 1 : 0}o${opts.featureSignals.onRoadmap ? 1 : 0}w${opts.featureSignals.wontfixNoContributor ? 1 : 0}`
+            : "";
+        const cacheKey = `vet:${issueUrl}${sigKey}`;
         const cached = cache.getIfFresh(cacheKey, VETTING_CACHE_TTL_MS);
         if (cached &&
             typeof cached === "object" &&
@@ -213,6 +221,7 @@ export class IssueVetter {
             orgHasMergedPRs,
             repoQualityBonus,
             matchesPreferredCategory: matchesCategory,
+            featureSignals: opts?.featureSignals,
         });
         const starredRepos = this.stateReader.getStarredRepos();
         let searchPriority = "normal";
@@ -263,9 +272,16 @@ export class IssueVetter {
         let failedVettingCount = 0;
         let rateLimitFailures = 0;
         let attemptedCount = 0;
+        // Capture the first 401 so we can re-throw after in-flight tasks settle.
+        // Per-item tolerance is right for transient failures, but a 401 means
+        // the token is invalid and no other issue will succeed either —
+        // continuing to log per-issue warnings buries the actual problem.
+        let firstAuthError = null;
         for (const url of urls) {
             if (candidates.length >= maxResults)
                 break;
+            if (firstAuthError)
+                break; // stop scheduling once auth has failed
             attemptedCount++;
             const task = this.vetIssue(url)
                 .then((candidate) => {
@@ -278,6 +294,10 @@ export class IssueVetter {
                 }
             })
                 .catch((error) => {
+                if (getHttpStatusCode(error) === 401) {
+                    firstAuthError ??= error;
+                    return;
+                }
                 failedVettingCount++;
                 if (isRateLimitError(error)) {
                     rateLimitFailures++;
@@ -293,6 +313,12 @@ export class IssueVetter {
         }
         // Wait for remaining
         await Promise.allSettled(pending.values());
+        if (firstAuthError) {
+            if (candidates.length > 0) {
+                warn(MODULE, `Auth failed mid-batch after ${candidates.length} successful vet(s) — discarding partial results`);
+            }
+            throw firstAuthError;
+        }
         const allFailed = failedVettingCount === attemptedCount && attemptedCount > 0;
         if (allFailed) {
             warn(MODULE, `All ${attemptedCount} issue(s) failed vetting. ` +

package/dist/core/linked-pr.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Helpers for reasoning about linked PRs surfaced via the issue timeline.
+ *
+ * Currently scoped to detecting "stalled" PRs — open PRs that have not been
+ * updated in the last `STALLED_PR_THRESHOLD_DAYS` days. Stalled linked PRs
+ * are surfaced as revive opportunities (#97). Note: this module does NOT
+ * change scoring; the existing -30 penalty on issues with linked PRs is
+ * preserved. This is annotation-only.
+ */
+import type { LinkedPR } from "./schemas.js";
+/** Days of inactivity that classify a linked PR as "stalled". */
+export declare const STALLED_PR_THRESHOLD_DAYS = 30;
+/**
+ * Determine whether a linked PR is stalled (open + not updated in the
+ * last STALLED_PR_THRESHOLD_DAYS days). Returns false when the PR is
+ * closed/merged, when updatedAt is missing, or when the threshold isn't met.
+ */
+export declare function isLinkedPRStalled(linkedPR: LinkedPR | null | undefined, now?: Date, thresholdDays?: number): boolean;

package/dist/core/linked-pr.js

@@ -0,0 +1,25 @@
+/**
+ * Helpers for reasoning about linked PRs surfaced via the issue timeline.
+ *
+ * Currently scoped to detecting "stalled" PRs — open PRs that have not been
+ * updated in the last `STALLED_PR_THRESHOLD_DAYS` days. Stalled linked PRs
+ * are surfaced as revive opportunities (#97). Note: this module does NOT
+ * change scoring; the existing -30 penalty on issues with linked PRs is
+ * preserved. This is annotation-only.
+ */
+/** Days of inactivity that classify a linked PR as "stalled". */
+export const STALLED_PR_THRESHOLD_DAYS = 30;
+/**
+ * Determine whether a linked PR is stalled (open + not updated in the
+ * last STALLED_PR_THRESHOLD_DAYS days). Returns false when the PR is
+ * closed/merged, when updatedAt is missing, or when the threshold isn't met.
+ */
+export function isLinkedPRStalled(linkedPR, now = new Date(), thresholdDays = STALLED_PR_THRESHOLD_DAYS) {
+    if (!linkedPR || linkedPR.state !== "open" || !linkedPR.updatedAt)
+        return false;
+    const updated = new Date(linkedPR.updatedAt);
+    if (Number.isNaN(updated.getTime()))
+        return false;
+    const ageDays = (now.getTime() - updated.getTime()) / (1000 * 60 * 60 * 24);
+    return ageDays >= thresholdDays;
+}

package/dist/core/repo-health.js

@@ -73,6 +73,9 @@ export async function checkProjectHealth(octokit, owner, repo) {
         });
     }
     catch (error) {
+        if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
+            throw error;
+        }
         const errMsg = errorMessage(error);
         warn(MODULE, `Error checking project health for ${owner}/${repo}: ${errMsg}`);
         return {

package/dist/core/roadmap.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Roadmap scraping (#95) — fetches a repo's ROADMAP.md (or variant) and
+ * extracts referenced GitHub issue numbers. Used by feature-discovery to
+ * apply an `onRoadmap` bonus when the maintainer has publicly committed
+ * to an issue in their roadmap doc.
+ *
+ * Cached for 1 hour per repo. 404s are cached as empty sets so repos
+ * without a roadmap don't get re-probed every run.
+ *
+ * Auth (401) and rate-limit errors propagate, matching the rest of the
+ * codebase's error strategy. Other errors degrade gracefully (warn + empty).
+ */
+import type { Octokit } from "@octokit/rest";
+/**
+ * Parse markdown content for issue number references.
+ *
+ * Extracts:
+ *   - bare `#NNN` references that are not on a markdown heading line
+ *   - `<owner>/<repo>#NNN` cross-repo refs that match the repo we're parsing for
+ *   - `https://github.com/<owner>/<repo>/issues/NNN` URLs that match the
+ *     repo we're parsing for (URLs to other repos are ignored)
+ *
+ * The match for cross-repo `owner/repo#N` and full URLs is intentional:
+ * scattered references to unrelated repos in a roadmap shouldn't bump
+ * scores in those repos.
+ */
+export declare function parseRoadmapIssueRefs(content: string, owner: string, repo: string): Set<number>;
+/**
+ * Fetch and parse the repo's ROADMAP.md, returning the set of referenced
+ * issue numbers. Returns an empty set if no roadmap is found.
+ *
+ * Probes ROADMAP_PATHS sequentially until a 200 response is received.
+ * Auth/rate-limit errors propagate; other errors are logged and degrade
+ * to an empty set.
+ */
+export declare function fetchRoadmapIssueRefs(octokit: Octokit, owner: string, repo: string): Promise<Set<number>>;
+/** Test-only: clear the in-memory cache. */
+export declare function _clearRoadmapCacheForTests(): void;

package/dist/core/roadmap.js

@@ -0,0 +1,131 @@
+/**
+ * Roadmap scraping (#95) — fetches a repo's ROADMAP.md (or variant) and
+ * extracts referenced GitHub issue numbers. Used by feature-discovery to
+ * apply an `onRoadmap` bonus when the maintainer has publicly committed
+ * to an issue in their roadmap doc.
+ *
+ * Cached for 1 hour per repo. 404s are cached as empty sets so repos
+ * without a roadmap don't get re-probed every run.
+ *
+ * Auth (401) and rate-limit errors propagate, matching the rest of the
+ * codebase's error strategy. Other errors degrade gracefully (warn + empty).
+ */
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { warn } from "./logger.js";
+const MODULE = "roadmap";
+/** TTL for roadmap fetch results (1 hour). */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+/** Paths probed in priority order. First success wins. */
+const ROADMAP_PATHS = [
+    "ROADMAP.md",
+    "docs/ROADMAP.md",
+    ".github/ROADMAP.md",
+    "Roadmap.md",
+    "roadmap.md",
+];
+const roadmapCache = new Map();
+/** Drop expired entries. Called from each fetch. */
+function pruneCache() {
+    const cutoff = Date.now() - CACHE_TTL_MS;
+    for (const [key, value] of roadmapCache.entries()) {
+        if (value.fetchedAt < cutoff)
+            roadmapCache.delete(key);
+    }
+}
+/**
+ * Parse markdown content for issue number references.
+ *
+ * Extracts:
+ *   - bare `#NNN` references that are not on a markdown heading line
+ *   - `<owner>/<repo>#NNN` cross-repo refs that match the repo we're parsing for
+ *   - `https://github.com/<owner>/<repo>/issues/NNN` URLs that match the
+ *     repo we're parsing for (URLs to other repos are ignored)
+ *
+ * The match for cross-repo `owner/repo#N` and full URLs is intentional:
+ * scattered references to unrelated repos in a roadmap shouldn't bump
+ * scores in those repos.
+ */
+export function parseRoadmapIssueRefs(content, owner, repo) {
+    const refs = new Set();
+    const ownerRepoLower = `${owner}/${repo}`.toLowerCase();
+    // `owner/repo#N` cross-repo style refs — must match the current repo.
+    // We escape regex metachars in case repo names contain `.` or `-`.
+    const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const fullRefPattern = new RegExp(`\\b${escape(owner)}/${escape(repo)}#(\\d+)\\b`, "gi");
+    for (const m of content.matchAll(fullRefPattern)) {
+        const n = Number.parseInt(m[1], 10);
+        if (n > 0)
+            refs.add(n);
+    }
+    // Bare `#N` references, scanned line-by-line so we can skip markdown
+    // headings (`# title`, `## section`) — those aren't issue refs. We also
+    // strip out `owner/repo#N` matches first so `#N` in a cross-repo ref to
+    // a different repo doesn't leak in as a bare match.
+    const fullRefStripPattern = /\b[\w.-]+\/[\w.-]+#\d+\b/gi;
+    for (const line of content.split("\n")) {
+        if (/^\s*#+\s/.test(line))
+            continue;
+        const stripped = line.replace(fullRefStripPattern, "");
+        for (const m of stripped.matchAll(/(?:^|[^&\w])#(\d+)\b/g)) {
+            const n = Number.parseInt(m[1], 10);
+            if (n > 0)
+                refs.add(n);
+        }
+    }
+    // Full GitHub issue URLs scoped to this repo.
+    const urlPattern = /https?:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/issues\/(\d+)/gi;
+    for (const m of content.matchAll(urlPattern)) {
+        if (m[1].toLowerCase() === ownerRepoLower) {
+            const n = Number.parseInt(m[2], 10);
+            if (n > 0)
+                refs.add(n);
+        }
+    }
+    return refs;
+}
+/**
+ * Fetch and parse the repo's ROADMAP.md, returning the set of referenced
+ * issue numbers. Returns an empty set if no roadmap is found.
+ *
+ * Probes ROADMAP_PATHS sequentially until a 200 response is received.
+ * Auth/rate-limit errors propagate; other errors are logged and degrade
+ * to an empty set.
+ */
+export async function fetchRoadmapIssueRefs(octokit, owner, repo) {
+    const cacheKey = `${owner}/${repo}`.toLowerCase();
+    const cached = roadmapCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+        return cached.refs;
+    }
+    for (const path of ROADMAP_PATHS) {
+        try {
+            const { data } = await octokit.repos.getContent({ owner, repo, path });
+            if (!("content" in data))
+                continue;
+            const content = Buffer.from(data.content, "base64").toString("utf-8");
+            const refs = parseRoadmapIssueRefs(content, owner, repo);
+            roadmapCache.set(cacheKey, { refs, fetchedAt: Date.now() });
+            pruneCache();
+            return refs;
+        }
+        catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
+            const status = getHttpStatusCode(err);
+            if (status === 404)
+                continue; // path missing — try next
+            warn(MODULE, `Unexpected error fetching ${path} from ${owner}/${repo}: ${errorMessage(err)}`);
+            // Fall through and try next path.
+        }
+    }
+    // No roadmap found (or all probes errored softly). Cache the empty result
+    // so we don't re-probe every run.
+    const empty = new Set();
+    roadmapCache.set(cacheKey, { refs: empty, fetchedAt: Date.now() });
+    pruneCache();
+    return empty;
+}
+/** Test-only: clear the in-memory cache. */
+export function _clearRoadmapCacheForTests() {
+    roadmapCache.clear();
+}

package/dist/core/schemas.d.ts

@@ -94,6 +94,7 @@ export declare const LinkedPRSchema: z.ZodObject<{
     }>;
     merged: z.ZodBoolean;
     url: z.ZodString;
+    updatedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const IssueVettingResultSchema: z.ZodObject<{
     passedAllChecks: z.ZodBoolean;
@@ -129,6 +130,7 @@ export declare const IssueVettingResultSchema: z.ZodObject<{
         }>;
         merged: z.ZodBoolean;
         url: z.ZodString;
+        updatedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     notes: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -182,6 +184,7 @@ export declare const TrackedIssueSchema: z.ZodObject<{
             }>;
             merged: z.ZodBoolean;
             url: z.ZodString;
+            updatedAt: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         notes: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
@@ -193,6 +196,10 @@ export declare const SkippedIssueSchema: z.ZodObject<{
     title: z.ZodString;
     skippedAt: z.ZodString;
 }, z.core.$strip>;
+export declare const HorizonSchema: z.ZodEnum<{
+    "quick-win": "quick-win";
+    "bigger-bet": "bigger-bet";
+}>;
 export declare const SavedCandidateSchema: z.ZodObject<{
     issueUrl: z.ZodString;
     repo: z.ZodString;
@@ -209,6 +216,10 @@ export declare const SavedCandidateSchema: z.ZodObject<{
     firstSeenAt: z.ZodString;
     lastSeenAt: z.ZodString;
     lastScore: z.ZodNumber;
+    horizon: z.ZodOptional<z.ZodEnum<{
+        "quick-win": "quick-win";
+        "bigger-bet": "bigger-bet";
+    }>>;
 }, z.core.$strip>;
 export declare const PersistenceModeSchema: z.ZodEnum<{
     local: "local";
@@ -254,6 +265,8 @@ export declare const ScoutPreferencesSchema: z.ZodObject<{
     skipBroadWhenSufficientResults: z.ZodDefault<z.ZodNumber>;
     slmTriageModel: z.ZodDefault<z.ZodString>;
     slmTriageHost: z.ZodDefault<z.ZodString>;
+    featuresAnchorThreshold: z.ZodDefault<z.ZodNumber>;
+    featuresSplitRatio: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const ScoutStateSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -297,6 +310,8 @@ export declare const ScoutStateSchema: z.ZodObject<{
         skipBroadWhenSufficientResults: z.ZodDefault<z.ZodNumber>;
         slmTriageModel: z.ZodDefault<z.ZodString>;
         slmTriageHost: z.ZodDefault<z.ZodString>;
+        featuresAnchorThreshold: z.ZodDefault<z.ZodNumber>;
+        featuresSplitRatio: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     repoScores: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         repo: z.ZodString;
@@ -347,6 +362,10 @@ export declare const ScoutStateSchema: z.ZodObject<{
         firstSeenAt: z.ZodString;
         lastSeenAt: z.ZodString;
         lastScore: z.ZodNumber;
+        horizon: z.ZodOptional<z.ZodEnum<{
+            "quick-win": "quick-win";
+            "bigger-bet": "bigger-bet";
+        }>>;
     }, z.core.$strip>>>;
     skippedIssues: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
@@ -372,6 +391,7 @@ export type LinkedPR = z.infer<typeof LinkedPRSchema>;
 export type IssueVettingResult = z.infer<typeof IssueVettingResultSchema>;
 export type TrackedIssue = z.infer<typeof TrackedIssueSchema>;
 export type ScoutPreferences = z.infer<typeof ScoutPreferencesSchema>;
+export type Horizon = z.infer<typeof HorizonSchema>;
 export type SavedCandidate = z.infer<typeof SavedCandidateSchema>;
 export type SkippedIssue = z.infer<typeof SkippedIssueSchema>;
 export type ScoutState = z.infer<typeof ScoutStateSchema>;

package/dist/core/schemas.js

@@ -95,6 +95,12 @@ export const LinkedPRSchema = z.object({
     state: z.enum(["open", "closed"]),
     merged: z.boolean(),
     url: z.string(),
+    /**
+     * ISO-8601 timestamp of the linked PR's last update. Optional so existing
+     * persisted state validates unchanged. Used by `isLinkedPRStalled` to
+     * surface stale revive opportunities (#97).
+     */
+    updatedAt: z.string().optional(),
 });
 export const IssueVettingResultSchema = z.object({
     passedAllChecks: z.boolean(),
@@ -131,6 +137,7 @@ export const SkippedIssueSchema = z.object({
     skippedAt: z.string(),
 });
 // ── Saved candidate schema ─────────────────────────────────────────
+export const HorizonSchema = z.enum(["quick-win", "bigger-bet"]);
 export const SavedCandidateSchema = z.object({
     issueUrl: z.string(),
     repo: z.string(),
@@ -143,6 +150,7 @@ export const SavedCandidateSchema = z.object({
     firstSeenAt: z.string(),
     lastSeenAt: z.string(),
     lastScore: z.number(),
+    horizon: HorizonSchema.optional(),
 });
 // ── Scout preferences schema ────────────────────────────────────────
 export const PersistenceModeSchema = z.enum(["local", "gist"]);
@@ -177,6 +185,18 @@ export const ScoutPreferencesSchema = z.object({
      * local network.
      */
     slmTriageHost: z.string().default(""),
+    /**
+     * Minimum merged-PR count for a repo to qualify as an anchor in
+     * `scout features` (#98). Lowering surfaces more anchors at the cost
+     * of weaker prior engagement signal.
+     */
+    featuresAnchorThreshold: z.number().int().min(1).max(50).default(3),
+    /**
+     * Quick-wins / bigger-bets split ratio for `scout features` (#99).
+     * 0.6 means 60% quick wins, 40% bigger bets when both pools are
+     * abundant. Deficits redirect to the other bucket.
+     */
+    featuresSplitRatio: z.number().min(0).max(1).default(0.6),
 });
 // ── Root state schema ───────────────────────────────────────────────
 export const ScoutStateSchema = z.object({

package/dist/core/search-phases.js

@@ -370,6 +370,8 @@ export async function searchInRepos(octokit, vetter, repos, baseQualifiers, labe
             }
         }
         catch (error) {
+            if (getHttpStatusCode(error) === 401)
+                throw error;
             failedBatches++;
             if (isRateLimitError(error)) {
                 rateLimitFailures++;

package/dist/index.d.ts

@@ -16,9 +16,12 @@
  */
 export { createScout, OssScout } from "./scout.js";
 export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, AntiLLMPolicyResult, AntiLLMPolicySourceFile, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from "./core/types.js";
-export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, LinkedPR, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, StoredOpenPR, SearchStrategy, SkippedIssue, } from "./core/schemas.js";
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
+export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, LinkedPR, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, StoredOpenPR, SearchStrategy, SkippedIssue, Horizon, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, HorizonSchema, } 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";
+export { IssueVetter, type ScoutStateReader, type FeatureSignals, } from "./core/issue-vetting.js";
 export { scanForAntiLLMPolicy, ANTI_LLM_KEYWORDS, } from "./core/anti-llm-policy.js";
+export { discoverFeatures, resolveAnchorRepos, classifyHorizon, splitByHorizon, ANCHOR_THRESHOLD, FEATURE_LABELS, NO_ANCHORS_MESSAGE, NO_RESULTS_MESSAGE, type FeatureCandidate, type FeatureSearchResult, type DiscoverFeaturesOptions, } from "./core/feature-discovery.js";
+export { isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from "./core/linked-pr.js";
+export { fetchRoadmapIssueRefs, parseRoadmapIssueRefs, } from "./core/roadmap.js";

package/dist/index.js

@@ -17,10 +17,16 @@
 // Main API
 export { createScout, OssScout } from "./scout.js";
 // Schemas (for consumers who need runtime validation)
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, HorizonSchema, } from "./core/schemas.js";
 // Utilities
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 // Internal classes (for advanced use)
 export { IssueDiscovery } from "./core/issue-discovery.js";
-export { IssueVetter } from "./core/issue-vetting.js";
+export { IssueVetter, } from "./core/issue-vetting.js";
 export { scanForAntiLLMPolicy, ANTI_LLM_KEYWORDS, } from "./core/anti-llm-policy.js";
+// Feature discovery API
+export { discoverFeatures, resolveAnchorRepos, classifyHorizon, splitByHorizon, ANCHOR_THRESHOLD, FEATURE_LABELS, NO_ANCHORS_MESSAGE, NO_RESULTS_MESSAGE, } from "./core/feature-discovery.js";
+// Linked-PR helpers (#97)
+export { isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from "./core/linked-pr.js";
+// Roadmap scraping (#95)
+export { fetchRoadmapIssueRefs, parseRoadmapIssueRefs, } from "./core/roadmap.js";

package/dist/scout.d.ts

@@ -5,7 +5,8 @@
  * Implements ScoutStateReader to bridge state with the search engine.
  */
 import type { ScoutStateReader } from "./core/issue-vetting.js";
-import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue } from "./core/schemas.js";
+import { type FeatureSearchResult } from "./core/feature-discovery.js";
+import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue, Horizon } from "./core/schemas.js";
 import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from "./core/types.js";
 import { GistStateStore } from "./core/gist-state-store.js";
 /**
@@ -51,6 +52,26 @@ export declare class OssScout implements ScoutStateReader {
      * Vet a single issue URL for claimability.
      */
     vetIssue(issueUrl: string): Promise<IssueCandidate>;
+    /**
+     * `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.
+     */
+    features(options?: {
+        count?: number;
+        anchorThreshold?: number;
+        splitRatio?: number;
+        broad?: boolean;
+    }): Promise<FeatureSearchResult>;
     /**
      * Re-vet all saved results with bounded concurrency.
      * Classifies each as still_available, claimed, has_pr, closed, or error.
@@ -106,7 +127,9 @@ export declare class OssScout implements ScoutStateReader {
      * If a candidate already exists, updates score/recommendation/lastSeenAt
      * but preserves firstSeenAt.
      */
-    saveResults(candidates: IssueCandidate[]): void;
+    saveResults(candidates: Array<IssueCandidate | (IssueCandidate & {
+        horizon?: Horizon;
+    })>): void;
     /**
      * Get all saved results.
      */