@oss-scout/core 0.8.0 → 0.9.1

package/dist/core/feature-discovery.js

@@ -0,0 +1,380 @@
+/**
+ * Feature Discovery — orchestrates `scout features` mode: surfaces
+ * feature-scoped contribution opportunities in repos where the user has
+ * 3+ merged PRs, ranked into separate "quick wins" and "bigger bets" buckets.
+ *
+ * Reuses existing infrastructure:
+ * - issue-vetting.ts    — per-issue vetting + scoring (with featureSignals)
+ * - issue-scoring.ts    — viability score (existing weights + feature bonuses)
+ * - http-cache.ts       — response cache
+ * - errors.ts           — auth/rate-limit propagation
+ *
+ * No state singletons — anchor repos are resolved from RepoScore[] passed in.
+ */
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { warn } from "./logger.js";
+import { sleep } from "./utils.js";
+import { fetchRoadmapIssueRefs } from "./roadmap.js";
+const MODULE = "feature-discovery";
+/** Delay between per-repo issue lists, mirroring search-phases.INTER_QUERY_DELAY_MS. */
+const INTER_REPO_DELAY_MS = 2000;
+/** Minimum viability score for a feature candidate to surface — same as scout search. */
+const MIN_VIABILITY_SCORE = 40;
+/** Default minimum merged-PR count for a repo to qualify as an anchor. */
+export const ANCHOR_THRESHOLD = 3;
+/** Default quick-wins / bigger-bets split ratio (60/40). */
+export const DEFAULT_SPLIT_RATIO = 0.6;
+/**
+ * Resolve anchor repos: those with mergedPRCount >= threshold (default 3),
+ * sorted by mergedPRCount descending. ScoutState stores repoScores as a
+ * Record<string, RepoScore>, so we read its values.
+ *
+ * @param threshold Override minimum merged-PR count (#98).
+ */
+export function resolveAnchorRepos(repoScores, threshold = ANCHOR_THRESHOLD) {
+    return Object.values(repoScores)
+        .filter((rs) => rs.mergedPRCount >= threshold)
+        .sort((a, b) => b.mergedPRCount - a.mergedPRCount)
+        .map((rs) => rs.repo);
+}
+/** Labels that promote an issue to the "bigger-bet" bucket. */
+export const BIGGER_BET_LABELS = new Set([
+    "roadmap",
+    "accepted-rfc",
+    "proposal",
+]);
+/**
+ * Classify an issue into "quick-win" or "bigger-bet" based on
+ * maintainer-commitment signals (milestone presence, label set, ROADMAP.md
+ * membership). Roadmap membership (#95) is treated as an explicit
+ * maintainer commitment and forces the bigger-bet horizon.
+ */
+export function classifyHorizon(input) {
+    if (input.hasMilestone || input.isOnRoadmap)
+        return "bigger-bet";
+    for (const label of input.labels) {
+        if (BIGGER_BET_LABELS.has(label.toLowerCase()))
+            return "bigger-bet";
+    }
+    return "quick-win";
+}
+/**
+ * Split feature candidates into two buckets respecting a configurable
+ * quick-wins / bigger-bets ratio (default 60/40). If either bucket is
+ * short, redirect the deficit to the other bucket. Each bucket is
+ * sorted by viabilityScore descending.
+ *
+ * @param ratio Fraction (0..1) of `count` to allocate to quick wins (#99).
+ */
+export function splitByHorizon(candidates, count, ratio = DEFAULT_SPLIT_RATIO) {
+    const allQuick = candidates
+        .filter((c) => c.horizon === "quick-win")
+        .sort((a, b) => b.viabilityScore - a.viabilityScore);
+    const allBigger = candidates
+        .filter((c) => c.horizon === "bigger-bet")
+        .sort((a, b) => b.viabilityScore - a.viabilityScore);
+    const targetQuick = Math.round(count * ratio);
+    const targetBigger = count - targetQuick;
+    const quickTaken = Math.min(allQuick.length, targetQuick);
+    const biggerTaken = Math.min(allBigger.length, targetBigger);
+    // Redirect deficits.
+    let quickFinal = quickTaken;
+    let biggerFinal = biggerTaken;
+    const quickDeficit = targetQuick - quickTaken;
+    const biggerDeficit = targetBigger - biggerTaken;
+    if (quickDeficit > 0) {
+        biggerFinal = Math.min(allBigger.length, biggerFinal + quickDeficit);
+    }
+    if (biggerDeficit > 0) {
+        quickFinal = Math.min(allQuick.length, quickFinal + biggerDeficit);
+    }
+    return {
+        quickWins: allQuick.slice(0, quickFinal),
+        biggerBets: allBigger.slice(0, biggerFinal),
+    };
+}
+/** Feature labels used to filter issues. Any-of match. */
+export const FEATURE_LABELS = [
+    "enhancement",
+    "feature",
+    "feature-request",
+    "proposal",
+    "roadmap",
+    "accepted-rfc",
+];
+/** Labels excluded from feature-mode results (overlap with `scout` territory). */
+export const FEATURE_EXCLUSION_LABELS = new Set([
+    "good first issue",
+    "bug",
+    "documentation",
+]);
+/**
+ * Labels that signal "the maintainer wants outside contributions". When any
+ * is present, combined with no linked PR and an issue age >= 60 days, the
+ * issue is treated as wontfix-no-contributor (#96).
+ */
+export const WONTFIX_NO_CONTRIBUTOR_LABELS = new Set([
+    "help wanted",
+    "contributions welcome",
+    "up-for-grabs",
+    "bounty",
+    "pinned",
+    "unmaintained",
+]);
+/** Minimum days an issue must be open to qualify as wontfix-no-contributor. */
+export const WONTFIX_MIN_AGE_DAYS = 60;
+/**
+ * Pure detector for the "wontfix because no contributor stepped up" pattern (#96).
+ *
+ * True when:
+ *   - issue carries any of WONTFIX_NO_CONTRIBUTOR_LABELS, AND
+ *   - issue has been open at least `minAgeDays` days (default 60)
+ *
+ * The orchestrator already filters out assigned issues before reaching the
+ * vetter. Linked-PR cases are deliberately not gated here: the existing
+ * -30 viability penalty for `hasExistingPR` already discounts those, and
+ * checking `hasLinkedPR` would require deferring scoring until after vet,
+ * doubling the work for a marginally cleaner signal.
+ */
+export function detectWontfixNoContributor(input) {
+    const matched = input.labels.some((l) => WONTFIX_NO_CONTRIBUTOR_LABELS.has(l.toLowerCase()));
+    if (!matched)
+        return false;
+    const created = new Date(input.createdAt);
+    if (Number.isNaN(created.getTime()))
+        return false;
+    const now = input.now ?? new Date();
+    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
+    return ageDays >= (input.minAgeDays ?? WONTFIX_MIN_AGE_DAYS);
+}
+export const NO_ANCHORS_MESSAGE = "No anchor repos yet (need 3+ merged PRs in a repo). Try `scout search` to build relationships first.";
+export const NO_RESULTS_MESSAGE = "No open feature opportunities in your anchor repos right now. Check back next week, or try `scout search` for fix-mode work.";
+function extractLabels(item) {
+    if (!Array.isArray(item.labels))
+        return [];
+    return item.labels
+        .map((l) => (typeof l === "string" ? l : l?.name))
+        .filter((s) => typeof s === "string");
+}
+function isFeatureIssue(item) {
+    const labels = extractLabels(item).map((l) => l.toLowerCase());
+    if (labels.length === 0)
+        return false;
+    if (labels.some((l) => FEATURE_EXCLUSION_LABELS.has(l)))
+        return false;
+    return labels.some((l) => FEATURE_LABELS.includes(l));
+}
+/**
+ * Orchestrate `scout features`: anchor resolution → per-repo issue listing
+ * → feature-signal extraction → vetting → horizon classification → bucket split.
+ *
+ * Returns separate "quick wins" and "bigger bets" buckets per the 60/40 target,
+ * with a human-friendly message when no anchors qualify or no candidates pass
+ * the viability threshold.
+ *
+ * Auth (401) and rate-limit errors propagate. Per-repo and per-issue failures
+ * degrade gracefully via `warn`.
+ */
+export async function discoverFeatures(opts) {
+    const anchorRepos = resolveAnchorRepos(opts.repoScores, opts.anchorThreshold);
+    if (anchorRepos.length === 0) {
+        return {
+            quickWins: [],
+            biggerBets: [],
+            anchorRepos: [],
+            message: NO_ANCHORS_MESSAGE,
+        };
+    }
+    const candidates = [];
+    for (let i = 0; i < anchorRepos.length; i++) {
+        if (i > 0)
+            await sleep(INTER_REPO_DELAY_MS);
+        const [owner, repo] = anchorRepos[i].split("/");
+        // Issues list and roadmap fetch run in parallel — roadmap scraping (#95)
+        // adds at most one extra GET per anchor repo and the result is reused
+        // across every issue in this loop iteration.
+        let response;
+        let roadmapRefs;
+        try {
+            const [listResp, refs] = await Promise.all([
+                opts.octokit.issues.listForRepo({
+                    owner,
+                    repo,
+                    state: "open",
+                    sort: "updated",
+                    direction: "desc",
+                    per_page: 20,
+                }),
+                fetchRoadmapIssueRefs(opts.octokit, owner, repo),
+            ]);
+            response = listResp;
+            roadmapRefs = refs;
+        }
+        catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
+            warn(MODULE, `failed to list issues for ${anchorRepos[i]}: ${errorMessage(err)}`);
+            continue;
+        }
+        const items = response.data.filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it));
+        for (const item of items) {
+            const labels = extractLabels(item);
+            const hasMilestone = !!item.milestone;
+            const reactions = item.reactions?.total_count ?? 0;
+            const comments = item.comments ?? 0;
+            const wontfixNoContributor = item.created_at
+                ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
+                : false;
+            const onRoadmap = typeof item.number === "number" && roadmapRefs.has(item.number);
+            let candidate;
+            try {
+                candidate = await opts.vetter.vetIssue(item.html_url, {
+                    featureSignals: {
+                        reactions,
+                        comments,
+                        hasMilestone,
+                        wontfixNoContributor,
+                        onRoadmap,
+                    },
+                });
+            }
+            catch (err) {
+                if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                    throw err;
+                warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
+                continue;
+            }
+            const horizon = classifyHorizon({
+                hasMilestone,
+                labels,
+                isOnRoadmap: onRoadmap,
+            });
+            candidates.push({ ...candidate, horizon });
+        }
+    }
+    // Drop low-viability results — same threshold as scout search.
+    const passing = candidates.filter((c) => c.viabilityScore >= MIN_VIABILITY_SCORE);
+    const split = splitByHorizon(passing, opts.count, opts.splitRatio);
+    const total = split.quickWins.length + split.biggerBets.length;
+    return {
+        ...split,
+        anchorRepos,
+        message: total === 0 ? NO_RESULTS_MESSAGE : null,
+    };
+}
+// ── Broad / cross-repo mode (#100) ──────────────────────────────────────
+export const NO_BROAD_RESULTS_MESSAGE = "No open feature opportunities matched your filters. Try widening your language preferences in `scout config`.";
+const DEFAULT_BROAD_MAX_TO_VET = 30;
+/**
+ * Build a GitHub Search query for cross-repo feature discovery.
+ *
+ * Exported separately from `discoverFeaturesBroad` so the query construction
+ * is independently testable without mocking the Search API.
+ */
+export function buildBroadFeatureSearchQuery(opts) {
+    const parts = ["is:issue", "is:open", "no:assignee"];
+    // Feature labels — any-of via parenthesized OR.
+    const labelClause = FEATURE_LABELS.map((l) => `label:"${l}"`).join(" OR ");
+    parts.push(`(${labelClause})`);
+    // Exclude labels that overlap with `scout` territory.
+    for (const excl of FEATURE_EXCLUSION_LABELS) {
+        parts.push(`-label:"${excl}"`);
+    }
+    // Languages — skip the filter when "any" is the only preference, since
+    // GitHub Search has no `language:any` operator.
+    const languages = (opts.languages ?? []).filter((l) => l && l.toLowerCase() !== "any");
+    if (languages.length > 0) {
+        const langClause = languages.map((l) => `language:${l}`).join(" OR ");
+        parts.push(`(${langClause})`);
+    }
+    // User exclusions.
+    for (const repo of opts.excludeRepos ?? []) {
+        parts.push(`-repo:${repo}`);
+    }
+    for (const org of opts.excludeOrgs ?? []) {
+        parts.push(`-user:${org}`);
+    }
+    return parts.join(" ");
+}
+/**
+ * Orchestrate broad / cross-repo feature discovery (#100). Bypasses anchor
+ * resolution; runs a single GitHub Search API query for feature-labeled
+ * open issues across the entire ecosystem, filtered by the user's language
+ * preferences and excluded repos/orgs.
+ *
+ * Designed for first-touch contributors who haven't yet built repo
+ * relationships and so wouldn't qualify under the default `scout features`
+ * anchor-based path.
+ *
+ * Auth (401) and rate-limit errors propagate; per-issue vet failures
+ * degrade gracefully.
+ */
+export async function discoverFeaturesBroad(opts) {
+    const query = buildBroadFeatureSearchQuery({
+        languages: opts.languages,
+        excludeRepos: opts.excludeRepos,
+        excludeOrgs: opts.excludeOrgs,
+    });
+    const maxToVet = opts.maxToVet ?? DEFAULT_BROAD_MAX_TO_VET;
+    let items;
+    try {
+        const response = await opts.octokit.search.issuesAndPullRequests({
+            q: query,
+            sort: "interactions",
+            order: "desc",
+            per_page: maxToVet,
+        });
+        items = response.data.items.filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it));
+    }
+    catch (err) {
+        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+            throw err;
+        warn(MODULE, `broad feature search failed: ${errorMessage(err)}`);
+        return {
+            quickWins: [],
+            biggerBets: [],
+            anchorRepos: [],
+            message: NO_BROAD_RESULTS_MESSAGE,
+        };
+    }
+    const candidates = [];
+    for (const item of items) {
+        const labels = extractLabels(item);
+        const hasMilestone = !!item.milestone;
+        const reactions = item.reactions?.total_count ?? 0;
+        const comments = item.comments ?? 0;
+        const wontfixNoContributor = item.created_at
+            ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
+            : false;
+        let candidate;
+        try {
+            candidate = await opts.vetter.vetIssue(item.html_url, {
+                featureSignals: {
+                    reactions,
+                    comments,
+                    hasMilestone,
+                    wontfixNoContributor,
+                    // Roadmap scraping is per-repo and would require an extra fetch
+                    // per unique repo in the broad result set — deliberately skipped
+                    // here to keep the broad path cheap. Anchor mode keeps the bonus.
+                },
+            });
+        }
+        catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
+            warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
+            continue;
+        }
+        const horizon = classifyHorizon({ hasMilestone, labels });
+        candidates.push({ ...candidate, horizon });
+    }
+    const passing = candidates.filter((c) => c.viabilityScore >= MIN_VIABILITY_SCORE);
+    const split = splitByHorizon(passing, opts.count, opts.splitRatio);
+    const total = split.quickWins.length + split.biggerBets.length;
+    return {
+        ...split,
+        anchorRepos: [],
+        message: total === 0 ? NO_BROAD_RESULTS_MESSAGE : null,
+    };
+}

package/dist/core/issue-discovery.js

@@ -21,7 +21,7 @@ import { debug, info, warn } from "./logger.js";
 import { isDocOnlyIssue, applyPerRepoCap, } from "./issue-filtering.js";
 import { IssueVetter } from "./issue-vetting.js";
 import { getTopicsForCategories } from "./category-mapping.js";
-import { buildEffectiveLabels, interleaveArrays, cachedSearchIssues, fetchIssuesFromMaintainedRepos, filterVetAndScore, fetchIssuesFromKnownRepos, searchWithChunkedLabels, } from "./search-phases.js";
+import { buildEffectiveLabels, interleaveArrays, cachedSearchIssues, fetchIssuesFromMaintainedRepos, filterVetAndScore, fetchIssuesFromKnownRepos, searchAcrossLanguagesAndLabels, } from "./search-phases.js";
 const MODULE = "issue-discovery";
 /** If remaining search quota is below this, skip heavy phases (2, 3). */
 const LOW_BUDGET_THRESHOLD = 20;
@@ -83,7 +83,7 @@ async function runPhase1(octokit, vetter, repos, labels, maxResults, filterIssue
     };
 }
 /** Phase 2: General label-filtered search with multi-tier interleaving. */
-async function runPhase2(octokit, vetter, scopes, labels, configLabels, baseQualifiers, maxResults, minStars, phase0RepoSet, starredRepoSet, existingCandidates, filterIssues) {
+async function runPhase2(octokit, vetter, scopes, labels, configLabels, languages, isAnyLanguage, maxResults, minStars, phase0RepoSet, starredRepoSet, existingCandidates, filterIssues) {
     info(MODULE, "Phase 2: General issue search...");
     const seenRepos = new Set(existingCandidates.map((c) => c.issue.repo));
     // Build per-tier label groups. Multi-tier when 2+ scopes; single-tier otherwise.
@@ -112,7 +112,7 @@ async function runPhase2(octokit, vetter, scopes, labels, configLabels, baseQual
     let rateLimitHit = false;
     for (const { tier, tierLabels } of tierLabelGroups) {
         try {
-            const allItems = await searchWithChunkedLabels(octokit, tierLabels, 0, (labelQ) => `${baseQualifiers} ${labelQ}`.replace(/  +/g, " ").trim(), budgetPerTier * 3);
+            const allItems = await searchAcrossLanguagesAndLabels(octokit, languages, isAnyLanguage, tierLabels, (langQ) => `is:issue is:open ${langQ} no:assignee`.replace(/  +/g, " ").trim(), budgetPerTier * 3);
             info(MODULE, `Phase 2 [${tier}]: processing ${allItems.length} items...`);
             const { candidates: tierCandidates, allVetFailed, rateLimitHit: vetRateLimitHit, } = await filterVetAndScore(vetter, allItems, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], budgetPerTier, minStars, `Phase 2 [${tier}]`);
             tierResults.push(tierCandidates);
@@ -337,9 +337,6 @@ export class IssueDiscovery {
         const langQuery = isAnyLanguage
             ? ""
             : languages.map((l) => `language:${l}`).join(" ");
-        const baseQualifiers = `is:issue is:open ${langQuery} no:assignee`
-            .replace(/  +/g, " ")
-            .trim();
         // Build reusable filter
         const aiBlocklisted = new Set(config.aiPolicyBlocklist);
         if (aiBlocklisted.size > 0) {
@@ -427,7 +424,7 @@ export class IssueDiscovery {
                     info(MODULE, `Skipping broad phase delay: no results from previous phases, proceeding immediately`);
                 }
                 const remaining = maxResults - allCandidates.length;
-                const result = await runPhase2(this.octokit, this.vetter, scopes, labels, config.labels, baseQualifiers, remaining, minStars, phase0RepoSet, starredRepoSet, allCandidates, filterIssues);
+                const result = await runPhase2(this.octokit, this.vetter, scopes, labels, config.labels, languages, isAnyLanguage, remaining, minStars, phase0RepoSet, starredRepoSet, allCandidates, filterIssues);
                 allCandidates.push(...result.candidates);
                 phaseErrors["2"] = result.error;
                 if (result.rateLimitHit)

package/dist/core/issue-eligibility.js

@@ -36,12 +36,17 @@ function buildLinkedPRFromTimelineEvent(e, context) {
         warn(MODULE, `Cross-referenced PR #${issue.number} for ${ctx} missing html_url — skipping linkedPR metadata`);
         return null;
     }
+    // updatedAt is read directly from the timeline event's source.issue
+    // (issue.updated_at is exposed on the cross-reference payload), so no
+    // extra pulls.get round-trip is needed. Left undefined when absent —
+    // isLinkedPRStalled treats missing data as not-stalled.
     return {
         number: issue.number,
         author,
         state: issue.state === "closed" ? "closed" : "open",
         merged: !!issue.pull_request?.merged_at,
         url,
+        updatedAt: issue.updated_at,
     };
 }
 const MODULE = "issue-eligibility";

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

@@ -23,6 +23,22 @@ export interface ViabilityScoreParams {
     repoQualityBonus?: number;
     /** True when the repo matches one of the user's preferred project categories. */
     matchesPreferredCategory?: boolean;
+    /**
+     * Optional feature-mode signals. When present, applies reaction (cap +10),
+     * comment-depth (+5 if >=5), milestone (+5), and wontfixNoContributor
+     * (+10) bonuses. When absent, scoring behavior is unchanged.
+     *
+     * Note: `onRoadmap` is forwarded for cache-key uniqueness but does NOT
+     * contribute to the viability score (#95) — roadmap membership influences
+     * horizon classification only, not score.
+     */
+    featureSignals?: {
+        reactions: number;
+        comments: number;
+        hasMilestone: boolean;
+        onRoadmap?: boolean;
+        wontfixNoContributor?: boolean;
+    };
 }
 /**
  * Calculate viability score for an issue (0-100 scale)

package/dist/core/issue-scoring.js

@@ -92,6 +92,19 @@ export function calculateViabilityScore(params) {
     if (params.closedWithoutMergeCount > 0 && params.mergedPRCount === 0) {
         score -= 15;
     }
+    // Feature signals: reactions, comment depth, milestone, wontfix-no-contributor.
+    // Note: onRoadmap (#95) is intentionally NOT scored — roadmap membership is
+    // surfaced via the horizon classifier instead.
+    if (params.featureSignals) {
+        const fs = params.featureSignals;
+        score += Math.min(Math.floor(fs.reactions / 2), 10);
+        if (fs.comments >= 5)
+            score += 5;
+        if (fs.hasMilestone)
+            score += 5;
+        if (fs.wontfixNoContributor)
+            score += 10;
+    }
     // Clamp to 0-100
     return Math.max(0, Math.min(100, score));
 }

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

@@ -8,6 +8,28 @@
  */
 import { Octokit } from "@octokit/rest";
 import { type SearchPriority, type IssueCandidate, type ProjectCategory } from "./types.js";
+/**
+ * Feature-mode signals supplied by the caller (orchestrator) — the vetter
+ * does NOT extract these from the GitHub issue itself. When passed, they
+ * plumb through to `calculateViabilityScore` to apply reaction, comment-depth,
+ * milestone, roadmap, and wontfix-no-contributor bonuses.
+ */
+export type FeatureSignals = {
+    reactions: number;
+    comments: number;
+    hasMilestone: boolean;
+    /**
+     * Issue is referenced from the repo's ROADMAP.md. Strong maintainer-commitment
+     * signal — they've publicly committed to the work in a roadmap doc (#95).
+     */
+    onRoadmap?: boolean;
+    /**
+     * Issue exhibits "wontfix-no-contributor" pattern — labeled help-wanted /
+     * contributions-welcome / up-for-grabs / bounty, no linked PR, open >= 60
+     * days. Maintainer wants it; nobody has stepped up (#96).
+     */
+    wontfixNoContributor?: boolean;
+};
 /**
  * Read-only interface for accessing scout state during issue vetting.
  * Implementations may be backed by gist persistence, in-memory state, etc.
@@ -40,8 +62,15 @@ export declare 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.
      */
-    vetIssue(issueUrl: string): Promise<IssueCandidate>;
+    vetIssue(issueUrl: string, opts?: {
+        featureSignals?: FeatureSignals;
+    }): Promise<IssueCandidate>;
     /**
      * Vet multiple issues in parallel with concurrency limit
      */

package/dist/core/issue-vetting.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";

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/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;