@oss-scout/core 0.7.1 → 0.9.0

package/dist/cli.js

@@ -137,7 +137,10 @@ program
                     : c.recommendation === "skip"
                         ? "❌"
                         : "⚠️";
-                console.log(`  ${icon} ${c.issue.repo}#${c.issue.number} [${c.viabilityScore}/100]`);
+                const stalledTag = c.linkedPR?.isStalled
+                    ? " (stalled PR, revive opportunity)"
+                    : "";
+                console.log(`  ${icon} ${c.issue.repo}#${c.issue.number} [${c.viabilityScore}/100]${stalledTag}`);
                 console.log(`     ${c.issue.title}`);
                 console.log(`     ${c.issue.url}`);
                 if (c.repoScore) {
@@ -154,6 +157,92 @@ program
         handleCommandError(err, options);
     }
 });
+program
+    .command("features [count]")
+    .description("Surface feature-scoped opportunities in repos where you have 3+ merged PRs")
+    .option("--json", "Output as JSON")
+    .option("--anchor-threshold <n>", "Override featuresAnchorThreshold (1-50)")
+    .option("--split-ratio <r>", "Override featuresSplitRatio (0-1, e.g. 0.6)")
+    .option("--broad", "Bypass anchor repos; search feature issues across the ecosystem (first-touch mode)")
+    .action(async (count, options) => {
+    try {
+        const { runFeatures } = await import("./commands/features.js");
+        const maxResults = count ? parseInt(count, 10) : 10;
+        if (isNaN(maxResults) || maxResults < 1 || maxResults > 50) {
+            console.error("Error: count must be an integer between 1 and 50");
+            process.exit(1);
+        }
+        let anchorThreshold;
+        if (options.anchorThreshold !== undefined) {
+            const parsed = parseInt(options.anchorThreshold, 10);
+            if (isNaN(parsed) || parsed < 1 || parsed > 50) {
+                console.error("Error: --anchor-threshold must be an integer between 1 and 50");
+                process.exit(1);
+            }
+            anchorThreshold = parsed;
+        }
+        let splitRatio;
+        if (options.splitRatio !== undefined) {
+            const parsed = Number.parseFloat(options.splitRatio);
+            if (isNaN(parsed) || parsed < 0 || parsed > 1) {
+                console.error("Error: --split-ratio must be a number between 0 and 1");
+                process.exit(1);
+            }
+            splitRatio = parsed;
+        }
+        const state = loadLocalState();
+        const result = await runFeatures({
+            maxResults,
+            state,
+            anchorThreshold,
+            splitRatio,
+            broad: options.broad,
+        });
+        if (options.json) {
+            console.log(formatJsonSuccess(result));
+        }
+        else {
+            const total = result.quickWins.length + result.biggerBets.length;
+            if (result.message) {
+                console.log(`\n${result.message}\n`);
+            }
+            if (total === 0)
+                return;
+            const headerScope = options.broad
+                ? "across the ecosystem"
+                : "in your anchor repos";
+            console.log(`\n🎯 Feature opportunities ${headerScope} (${result.quickWins.length} quick wins + ${result.biggerBets.length} bigger bets)\n`);
+            if (!options.broad) {
+                console.log(`Anchor repos: ${result.anchorRepos.join(", ")}\n`);
+            }
+            if (result.quickWins.length) {
+                console.log("── Quick wins ─────────────────────────────────────────");
+                for (const c of result.quickWins) {
+                    const stalledTag = c.linkedPR?.isStalled
+                        ? " (stalled PR, revive opportunity)"
+                        : "";
+                    console.log(`  ${c.issue.repo}#${c.issue.number} [${c.viabilityScore}/100] ${c.issue.title}${stalledTag}`);
+                    console.log(`     ${c.issue.url}`);
+                }
+                console.log("");
+            }
+            if (result.biggerBets.length) {
+                console.log("── Bigger bets ────────────────────────────────────────");
+                for (const c of result.biggerBets) {
+                    const stalledTag = c.linkedPR?.isStalled
+                        ? " (stalled PR, revive opportunity)"
+                        : "";
+                    console.log(`  ${c.issue.repo}#${c.issue.number} [${c.viabilityScore}/100] ${c.issue.title}${stalledTag}`);
+                    console.log(`     ${c.issue.url}`);
+                }
+                console.log("");
+            }
+        }
+    }
+    catch (err) {
+        handleCommandError(err, options);
+    }
+});
 // ── results command ────────────────────────────────────────────────
 const resultsCmd = program
     .command("results")

package/dist/commands/config.js

@@ -28,6 +28,8 @@ const FIELD_CONFIGS = {
     githubUsername: { type: "string" },
     broadPhaseDelayMs: { type: "number" },
     skipBroadWhenSufficientResults: { type: "number" },
+    featuresAnchorThreshold: { type: "number" },
+    featuresSplitRatio: { type: "float" },
 };
 function parseBoolean(value) {
     const lower = value.toLowerCase();
@@ -44,6 +46,13 @@ function parseNumber(value, key) {
     }
     return num;
 }
+function parseFloat(value, key) {
+    const num = Number.parseFloat(value);
+    if (isNaN(num)) {
+        throw new ValidationError(`Invalid number for "${key}": "${value}"`);
+    }
+    return num;
+}
 function parseArrayValue(value) {
     return value
         .split(",")
@@ -96,6 +105,8 @@ export function runConfigShow() {
     console.log(`  persistence:          ${prefs.persistence}`);
     console.log(`  broadPhaseDelayMs:    ${prefs.broadPhaseDelayMs}ms (${(prefs.broadPhaseDelayMs / 1000).toFixed(0)}s)`);
     console.log(`  skipBroadWhenSufficientResults: ${prefs.skipBroadWhenSufficientResults}`);
+    console.log(`  featuresAnchorThreshold: ${prefs.featuresAnchorThreshold}`);
+    console.log(`  featuresSplitRatio:    ${prefs.featuresSplitRatio}`);
     console.log();
 }
 /**
@@ -125,6 +136,9 @@ export function runConfigSet(key, value) {
         case "number":
             prefs[key] = parseNumber(value, key);
             break;
+        case "float":
+            prefs[key] = parseFloat(value, key);
+            break;
         case "array": {
             const current = prefs[key] ?? [];
             prefs[key] = updateArray(current, value);

package/dist/commands/features.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Features command — surfaces feature opportunities in anchor repos.
+ */
+import type { ScoutState } from "../core/schemas.js";
+/**
+ * Linked-PR metadata surfaced on feature candidates. `isStalled` flags open
+ * PRs that haven't been updated for 30+ days — surfaced as revive
+ * opportunities (#97). Scoring is unchanged: the existing -30 viability
+ * penalty still applies.
+ */
+interface OutputLinkedPR {
+    number: number;
+    state: "open" | "closed";
+    url: string;
+    updatedAt?: string;
+    isStalled: boolean;
+}
+export interface FeaturesOutput {
+    quickWins: Array<{
+        issue: {
+            repo: string;
+            number: number;
+            title: string;
+            url: string;
+            labels: string[];
+        };
+        recommendation: "approve" | "skip" | "needs_review";
+        viabilityScore: number;
+        horizon: "quick-win";
+        linkedPR?: OutputLinkedPR;
+    }>;
+    biggerBets: Array<{
+        issue: {
+            repo: string;
+            number: number;
+            title: string;
+            url: string;
+            labels: string[];
+        };
+        recommendation: "approve" | "skip" | "needs_review";
+        viabilityScore: number;
+        horizon: "bigger-bet";
+        linkedPR?: OutputLinkedPR;
+    }>;
+    anchorRepos: string[];
+    message: string | null;
+}
+interface FeaturesCommandOptions {
+    maxResults: number;
+    state?: ScoutState;
+    anchorThreshold?: number;
+    splitRatio?: number;
+    /** Run the broad / cross-repo path (#100). */
+    broad?: boolean;
+}
+export declare function runFeatures(options: FeaturesCommandOptions): Promise<FeaturesOutput>;
+export {};

package/dist/commands/features.js

@@ -0,0 +1,76 @@
+/**
+ * Features command — surfaces feature opportunities in anchor repos.
+ */
+import { createScout } from "../scout.js";
+import { requireGitHubToken } from "../core/utils.js";
+import { saveLocalState } from "../core/local-state.js";
+import { isLinkedPRStalled } from "../core/linked-pr.js";
+function mapLinkedPR(c) {
+    const linkedPR = c.vettingResult.linkedPR;
+    if (!linkedPR)
+        return undefined;
+    return {
+        number: linkedPR.number,
+        state: linkedPR.state,
+        url: linkedPR.url,
+        updatedAt: linkedPR.updatedAt,
+        isStalled: isLinkedPRStalled(linkedPR),
+    };
+}
+function mapQuickWin(c) {
+    return {
+        issue: {
+            repo: c.issue.repo,
+            number: c.issue.number,
+            title: c.issue.title,
+            url: c.issue.url,
+            labels: c.issue.labels,
+        },
+        recommendation: c.recommendation,
+        viabilityScore: c.viabilityScore,
+        horizon: "quick-win",
+        linkedPR: mapLinkedPR(c),
+    };
+}
+function mapBiggerBet(c) {
+    return {
+        issue: {
+            repo: c.issue.repo,
+            number: c.issue.number,
+            title: c.issue.title,
+            url: c.issue.url,
+            labels: c.issue.labels,
+        },
+        recommendation: c.recommendation,
+        viabilityScore: c.viabilityScore,
+        horizon: "bigger-bet",
+        linkedPR: mapLinkedPR(c),
+    };
+}
+export async function runFeatures(options) {
+    const token = requireGitHubToken();
+    const scout = options.state
+        ? await createScout({
+            githubToken: token,
+            persistence: "provided",
+            initialState: options.state,
+        })
+        : await createScout({ githubToken: token });
+    const result = await scout.features({
+        count: options.maxResults,
+        anchorThreshold: options.anchorThreshold,
+        splitRatio: options.splitRatio,
+        broad: options.broad,
+    });
+    saveLocalState(scout.getState());
+    const persisted = await scout.checkpoint();
+    if (!persisted) {
+        console.error("Warning: changes saved locally but gist sync failed.");
+    }
+    return {
+        quickWins: result.quickWins.map(mapQuickWin),
+        biggerBets: result.biggerBets.map(mapBiggerBet),
+        anchorRepos: result.anchorRepos,
+        message: result.message,
+    };
+}

package/dist/commands/search.d.ts

@@ -24,6 +24,19 @@ export interface SearchOutput {
             isResponsive: boolean;
             lastMergedAt?: string;
         };
+        /**
+         * Metadata for the first cross-referenced PR linked to this issue, when
+         * one exists. `isStalled` flags open PRs that haven't been updated for
+         * 30+ days — surfaced as revive opportunities (#97). Scoring is
+         * unchanged: the existing -30 viability penalty still applies.
+         */
+        linkedPR?: {
+            number: number;
+            state: "open" | "closed";
+            url: string;
+            updatedAt?: string;
+            isStalled: boolean;
+        };
     }>;
     excludedRepos: string[];
     aiPolicyBlocklist: string[];

package/dist/commands/search.js

@@ -4,6 +4,7 @@
 import { createScout } from "../scout.js";
 import { requireGitHubToken } from "../core/utils.js";
 import { saveLocalState } from "../core/local-state.js";
+import { isLinkedPRStalled } from "../core/linked-pr.js";
 export async function runSearch(options) {
     const token = requireGitHubToken();
     const scout = options.state
@@ -50,6 +51,15 @@ export async function runSearch(options) {
                         lastMergedAt: repoScoreRecord.lastMergedAt,
                     }
                     : undefined,
+                linkedPR: c.vettingResult.linkedPR
+                    ? {
+                        number: c.vettingResult.linkedPR.number,
+                        state: c.vettingResult.linkedPR.state,
+                        url: c.vettingResult.linkedPR.url,
+                        updatedAt: c.vettingResult.linkedPR.updatedAt,
+                        isStalled: isLinkedPRStalled(c.vettingResult.linkedPR),
+                    }
+                    : undefined,
             };
         }),
         excludedRepos: result.excludedRepos,

package/dist/core/bootstrap.js

@@ -51,6 +51,8 @@ export async function bootstrapScout(scout, token) {
         scout.setStarredRepos(starredRepos);
     }
     catch (err) {
+        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+            throw err;
         warn(MODULE, `Failed to fetch starred repos: ${errorMessage(err)}`);
         errors.push("starred repos fetch failed");
     }

package/dist/core/feature-discovery.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 type { Octokit } from "@octokit/rest";
+import type { RepoScore, Horizon } from "./schemas.js";
+import type { IssueCandidate } from "./types.js";
+import type { IssueVetter } from "./issue-vetting.js";
+/** Default minimum merged-PR count for a repo to qualify as an anchor. */
+export declare const ANCHOR_THRESHOLD = 3;
+/** Default quick-wins / bigger-bets split ratio (60/40). */
+export declare 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 declare function resolveAnchorRepos(repoScores: Record<string, RepoScore>, threshold?: number): string[];
+/** Labels that promote an issue to the "bigger-bet" bucket. */
+export declare const BIGGER_BET_LABELS: Set<string>;
+/**
+ * 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 declare function classifyHorizon(input: {
+    hasMilestone: boolean;
+    labels: string[];
+    isOnRoadmap?: boolean;
+}): Horizon;
+/** A vetted issue candidate stamped with its horizon classification. */
+export type FeatureCandidate = IssueCandidate & {
+    horizon: Horizon;
+};
+/**
+ * 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 declare function splitByHorizon(candidates: FeatureCandidate[], count: number, ratio?: number): {
+    quickWins: FeatureCandidate[];
+    biggerBets: FeatureCandidate[];
+};
+/** Feature labels used to filter issues. Any-of match. */
+export declare const FEATURE_LABELS: readonly ["enhancement", "feature", "feature-request", "proposal", "roadmap", "accepted-rfc"];
+/** Labels excluded from feature-mode results (overlap with `scout` territory). */
+export declare const FEATURE_EXCLUSION_LABELS: Set<string>;
+/**
+ * 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 declare const WONTFIX_NO_CONTRIBUTOR_LABELS: Set<string>;
+/** Minimum days an issue must be open to qualify as wontfix-no-contributor. */
+export declare 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 declare function detectWontfixNoContributor(input: {
+    labels: string[];
+    createdAt: string;
+    now?: Date;
+    minAgeDays?: number;
+}): boolean;
+export declare const NO_ANCHORS_MESSAGE = "No anchor repos yet (need 3+ merged PRs in a repo). Try `scout search` to build relationships first.";
+export declare 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.";
+export interface FeatureSearchResult {
+    quickWins: FeatureCandidate[];
+    biggerBets: FeatureCandidate[];
+    anchorRepos: string[];
+    message: string | null;
+}
+export interface DiscoverFeaturesOptions {
+    octokit: Octokit;
+    vetter: IssueVetter;
+    repoScores: Record<string, RepoScore>;
+    count: number;
+    /** Override default anchor threshold (3 merged PRs). */
+    anchorThreshold?: number;
+    /** Override default split ratio (0.6 = 60% quick wins, 40% bigger bets). */
+    splitRatio?: number;
+}
+/**
+ * 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 declare function discoverFeatures(opts: DiscoverFeaturesOptions): Promise<FeatureSearchResult>;
+export declare const NO_BROAD_RESULTS_MESSAGE = "No open feature opportunities matched your filters. Try widening your language preferences in `scout config`.";
+export interface DiscoverFeaturesBroadOptions {
+    octokit: Octokit;
+    vetter: IssueVetter;
+    count: number;
+    /** Languages from user preferences ("any" disables the filter). */
+    languages?: string[];
+    excludeRepos?: string[];
+    excludeOrgs?: string[];
+    /** Override default split ratio. */
+    splitRatio?: number;
+    /** Maximum search results to vet (default 30). */
+    maxToVet?: number;
+}
+/**
+ * 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 declare function buildBroadFeatureSearchQuery(opts: {
+    languages?: string[];
+    excludeRepos?: string[];
+    excludeOrgs?: string[];
+}): string;
+/**
+ * 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 declare function discoverFeaturesBroad(opts: DiscoverFeaturesBroadOptions): Promise<FeatureSearchResult>;